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Introduction 


The purpose of this book is to save Windows programers time. Most of us who fae been programming with Windows 
for a few years have become accustomed to having our desks cluttered with various books. Mine seems to always have 
four or five Windows Software Development Kit manuals, a well thumbed copy of Charles Petzold’s excellent book 
Programming Windows, several printouts of Sans: programs, and perhaps a few other books buried under the 
pile. 

The Windows Bible is an attempt to assemble most of the information you need in one place. Following the 
organization of the other Waite Group bibles, the Windows Bible is organized by subject. Each chapter covers a 
separate topic. The chapter introductions cover basic concepts. The details are covered in the function and message 
descriptions. 

A key element to making the book useful is the use of short example Sree: They are particularly important 
with Windows, where functions are seldom used alone. Most functions require the support of a series of related 
functions and messages to do their task. The example programs show a function or message in context, with support- 
ing functions in place, and with variables properly declared. 

The example programs in this book are different from examples used in Windows tutorials. Tutorials generally use 
longer example programs, with many functions and messages demonstrated at one time. The examples in the Win- 
dows Bible are as short as possible. Their only purpose is to demonstrate one function or message or at most a few 
related functions or messages. They do show the proper use of the function or message, without a lot of other distrac- 
tions. 

In some cases, the emphasis on keeping the examples short and clear caused me to write what borders on riiling . 
simplistic code. For example, the preferred way to find out the corre<t text line spacing is to use the GetTextMetrics() 
function. It determines character heights on the screen. This assures that the spacing will be correct, regardless of 
the video resolution used. In the Windows API Bible examples, fixed line spacing is used for demonstration output in 
chapters that do not focus on display of text. This avoids the distraction of having GetTextMetrics() show up in every, 
example. The correct usage of GetTextMetrics() is explained in the chapter on text output. 

The structure of the book groups related subjects. Chapter 1 is an introduction for those new to Windows. Chap- 
ters 2 to 5 deal with the creation of windows, and the related menu and scrolling functions. Chapters 6 to 9 cover the 
various aspects of Windows messages. Chapters 10 to 12 deal with output to the screen and printers. The remaining 
chapters cover separate topics which are only loosely related. 

One disadvantage to the organization by related subjects is that it is not possible to introduce the reader to each 
subject in succession. For example, several of the message hook functions in Chapter 8, Message Processing Func- 
tions, require the use of dynamic link libraries. DLLs are not covered until Chapter 28, Dynamic Link Libraries. 
Cross references are included in these cases. 

This book was completed using Windows version 3.0 and the Beta 1 pre-release of Windows version 3.1. Changes 
and additions to version 3.0 functions and messages that occur in version 3.1 are documented. In most cases, version 
3.1 adds optional features by providing new functions in dynamic _ libraries. This assures compatibility with soft- 
ware developed under version 3.0. 


Size constraints made it impossible to include all of the new Windows 3.1 features in one book. All of the funda- 
‘mental subjects and the material common to versions 3.0 and 3.1 are included. The new OLE (object linking and 


embedding) and True Type fonts are not covered. DDE (dynamic data exchange) is discussed using the message-- ~~ _ 


based protocols, but not using the version 3.1 DDEML library. I intend to cover these subjects in a separate volume, 
which is currently.under development. The material in the Windows API Bible will remain valid and is common to all 
Windows applications. . 

While writing the book I was surprised to find a number of functions that I had not run into in four years of 
Windows programming. Some of these more obscure functions turned out to be remarkably useful. The experienced 
reader may find the discussions of message hooks, communications and sound support, atoms, and dynamic data 

‘exchange (DDE), and the multiple document interface (MDI) worth reviewing. 

Good luck with your Windows projects! , 


_dim Conger 
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This chapter introduces Windows programming and develops the GENERIC.C program. GENERIC.C will serveasthe 
- basis for all of the examples in this book. 


Windows Programming Overview 


Ifyou have been programming in DOS or in a minicomputer environment, your first look at a Windows program may be 
a little disconcerting. Windows programs are different. The differences boil down to a few basic principles. 


1. Instead of telling the computer what to do one step at a time, Windows programs are structured to wait there until 
the program receives a message from Windows. Messages are statements like “The user just clicked a button with 
the mouse pointer—do something!” 


2. The Windows environment has built-in support for all the basic hardware such as the video display, memory, 
mouse, keyboard, and printers. Microsoft takes care of worrying about all of the latest hardware—freeing you to 
create applications. Programmers spend their time learning and using the 600 Windows functions, rather than 

writing their own code to support multiple printers, video cards, etc. 


8. Windows moves programs and data around in memory to make room for other program pieces and data. This 
_ Movement allows many programs to coexist in a fairly limited amount of memory, but it also means that the 
_ programmer cannot assume that anything will stay put for long. Windows gives you all of the tools you need to deal 
with moveable memory, but it takes a little getting used to. 


Despite these differences, Windows is not a difficult environment i in which to work. When you have gotten over 
_ the initial hurdle of writing a few simple programs, the tremendous built-in power of Windows will spoil you. It will be 
difficult for you to ever go back to more primitive environments. 

Ifyou are new to programming with the Windows environment, my main advice i is to dive in and try it. You will find. 
that most Windows programs are remarkably similar, so that when you have one running, the second one is a matter ~ 
of modification. One of the main goals of this book is to provide working examples for all of the Windows functions, 
saving you the time it takes by figuring out how every one of them is used. For efficiency, a simple “GENERIC” pro- 
gram, which is described in the next section, is used as the basis for most of the programming examples. 


Structure of a Windows Program 

~ Most Windows programs have two C functions in common, WinMain() and WndProc(). Only WinMain() is eid 
although WndProc() shows up in almost every. Windows program. WndProc() can be named anything you want, but 
most programmers name it WndProc(). WinMain() must be named “WinMain,” just like the main() function in a 
conventional C program. Any large program will have many other functions doing as for WndProc(), but these two 
functions will be there to begin. 


WinMain() - Calls several functions that tell the Windows environment about the properties of the program’s main 
window. This includes what color to paint the window, the name of the icon to show when the program is initial- 

' ized, where to find the program’s menu, etc. WinMain() also contains some standard code to process Windows 
messages to and from the program you are writing. WinMain() is also the entry ard exit point of the program, 
again like main() in.a conventional C program. 


WINDOWS API BIBLE 


leh... igeneric 
'-Do It! Quit — 


Ok, | did it! 


Fignire 1-1. The GENERIC Program’s Window.’ °° Figure 1-2. ee ele the “Do 1" Men 
Item. 


WndProc() - This is where you write the program logic. This function is usually called the “message processing - 
function”.as Windows messages are interpreted and acted upon Within this function. 


'.. Let’s take a look at a simple example. We will create a program that looks like Figure 1-1. The program creates a 
window with the title “generic” and with two menu items, “Do It!” and “Quit”. When the program is first run, it just sits 
there. 

Moving the mouse pointer to “Do It!” and clicking the left. mouse button causes ee to appear in the window, as - 
shown i in Figure 1-2. Clicking the “Quit” menu item causes the program to stop and the window to disappear. The 
minimize and maximize buttons i in the upper right corner work per standard Windows conventions, as does the system 
button i in the upper left corner. 


GENERIC. C Example Windows Pea ge ainiy 


Listing 1-1 shows all of the C code needed to make GENERIC.C. Although the sia jocks ne at first glance, it is 
remarkably short. Remember that this program creates a window that can be moved and sized onthe acre shrunken 
to an icon, expanded to the size of the screen, and which has a functioning menu. 


C>: Listing 1-1. GENERIC.C °°: 


/* generic.c . generic windows application */" in 
#include <windows. h> : /* window's header file - always included x] 
evncbude” pene sey 1 /* the application’ s HeACer: file */ ; 


int PASCAL WinMain (HANDLE. hinstance; HANDLE hpvevinetwace: LPSTR.lpszCmdLine, int nCmdShow) 


t : 7 : i /* variable types defined in windows. h AL 
HWND hWnd 5 «© {*® a handle'to a message */ 
MSG . oo MSG _.:: 7* a message */ 
WNDCLASS wndclass ; /* the window class */ 


ghinstance’> hinstance ; /* store instance handle ‘as global var. */ 


if (!hPrevinstance) _* /* load data into window class struct. */ 


unde tases Seyte -CS_HREDRAW | CS_’ VREDRAW ; 


wndclass. LpfnWndProc WndProc i 
wndclass.cbClsExtra z 
wndclass.cbWndExtra 0; 


wndclass.hInstance 
ic 74 wndclass.hIcon baa 
.. wndclass.hCursor : 
" wndclass.hbrBackground 
wndclass. lpszMenuName . 


hInstance ; 

LoadIcon ChInstance, gszAppName) ; 7 
LoadCursor . (NULL, IDC_ARROW) ; 
GetStockObject (WHITE _BRUSH) ; 
aseKEph one . ; 


Huu nt Ww er net 


fe 


wndclass.lpszClassName 
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Ss 


= gszAppName ; 


/* register the window class */ 


if (!RegisterClass (&wndclass)) 


return FALSE ; 


} . 

hWnd = CreateWindow ¢ /* create the program's window here */ 
gszAppName, /* class name */ 
gszAppName, /* window name */ 
WS_OVERLAPPEDWINDOW, /* window style */ 
CW_USEDEFAULT, /* x position on screen */ 
CW_USEDEFAULT, /* y position on screen */ 
CW_USEDEFAULT, , /* width of window */ 
CW_USEDEFAULT, /* height of window */ 
NULL, /* parent window handte (null = none) */ 
NULL, /* menu handle Cnull = use class menu) */° 
hInstance, /* instance handle */ 
NULL) ; /* lpstr (null = not used) */ 


ShowWindow (hWnd, nCmdShow) ; 
UpdateWindow (hWnd) ; 


/* make window visible */ 
/* send first WM_PAINT message */ 


/* the next while) loop is the “message Loop” */ 


while (GetMessage (&msg, NULL, 0, 0)) 


/* wait for a message */ 


/* does some key conversions */ 
/* sends message to WndProc() */ 


/* returns application's exit code */ 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG. lParam) 


/* device context handle */ 
/* process windows messages */ 
/* process menu items */ 


/* User hit the “Do it" menu item */ 
/* get device context */ 


10, 20, "Ok, I did it!", 13) ; 


ReleaseDC (hWnd, hDC) ; /* release device context */ 


/* send end of application message */ 


DestroyWindow (hWnd) ; 


/* stop application */ 


/* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


{ 
TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} 
return msg.wParam ; 
} 
{ 
HDC hDC ; 
switch CiMessage) 
{ 
case WM_COMMAND: 
switch CwParam) 
{ 
case IDM_DOIT: 
hDC = GetDC ChWnd) ; 
TextOut ChDC, 
_ break ; 
' case IDM_QUIT: 
break ; 
} 
‘break ; 
case WM_DESTROY: 
PostQuitMessage (0) ; 
; break ; 
default: 
3 
return (OL) ; 
} ; 


The WinMain() function looks more complex than it is. The saving grace is that this function remains almost 
unchanged from one program to the next. You just copy that part into your next project. I will explain what it does in 


a moment. Let’s deal with the WinProc() function first. 


WinProc() processes messages from Windows. The messages are all integers, but for clarity they are given names 
in the WINDOWS.H header file. The two messages that GENERIC.C has to process are WM_COMMAND (a menu item - 
"was pressed), and WM_DESTROY (stop the application and close its window). The menu items are labeled IDM_DOIT 
- and IDM_QUIT. These names are defined in the program’s header file GENERIC.H, shown in Listing 1-2. 


‘ 
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> Listing 1-2. _ GENERIC. H Header File 
/* generic.h~ ‘ 
#define IDM_DOIT 1 /* menu item id values */ 
#define IDOM_QUIT 2 
/* global variables */ 

int ghInstance ; 
char gszAppName CJ = “generic” ; 
/* function prototypes */ 

tong FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 


When the user clicks the “Do It!” menu item, Windows sends the GENERIC program a WM_COMMAND message. 
Part of this message is the menu item number, in this case IDM_DOIT which we defined equal to one in GENERIC.H. 
When the WndProc() function in GENERIC.C gets this message, it executes the code: 


case IDM_DOIT:*/ : 
hDC = GetDC (hWnd) ;  /*® get device context */ 


TextOut Choc, 10, 20, "Ok, I did it!", 13) ; 
ReleaseDC chiind, hDC> ; /* Nolcawe device context */ 
break ; : 


‘The program uses the Windows function GetDC() to get some information about the video screen. Using this — 


information (called the device context), the program writes the words “Ok, I did it!” using the Windows function 
TextOut(). Finally, the memory tied up with the screen information is released by using ReleaseDC(). Those three 
functions put the words on the screen. 

Similarly, if, the user clicks the “Quit” menu item, the program executes the DestroyWindow() function. 
DestroyWindow() deletes the program's window, causing the program to end. This is called “terminating” an applica- 
tion. Windows sends the program the WM_DESTROY message, which is processed to exit the program. 

We have covered the operation of the WinProc() function. What about all of the code in the upper WinMain() 


function of GENERIC.C? Most of this code deals with creating the program’s main window. Creating a window is a_ 


three step process: . 


1. First, you have to create a window “class.” The class is dlegenibed' by filling i ina omen of data ina structure called 
wndclass. Here is an example of one of those lines. 


wndclass-hIcon = LoadiIcon Chinstance, gszAppName) ; 


~ Inthis case, every window created with this window class will refer to an icon with the same name as the program 


“generic.” The global variable gszAppName is defined in the GENERIC.H header file. Once all of the window class _ 


data is filled in, you notify Windows that you have created a new class of windows ae using the function 
RegisterClass(). 


2. Second, you use the CreateWindow() function to create one or more windows based on the window class. 


_ CreateWindow() passes more information on to windows, such as the style of the window, the background color, 
etc. 


3. Finally, you digplay the window by calling the ShowWindow() function. At the bottom of the WinMain() function © 


you will see the rather odd loop: 


while (GetMessage (&msg, NULL, 0, 0)) /* the message Loop */ | 
. £ : : 
TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} 


This loop, called the message loop, is in every Windows program. Windows passes all of the messages to the 


program via the functions in this loop. There are a few other functions that can be used in the message loop for special 

purposes like menu accelerator keys, but usually the loop will look exactly like this one. 
If you want to type i in the GENERIC.C program, compile it, and run it, you will need a couple of other small files. 
These files are the resource file that defines the menu, icon, and other resources used by the proprany, the definition 
i, 


ie 
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file that gives the compiler some guidance when creating the program; and the make file, to help automate compiling 
and linking the program. 

The resource file GENERIC.RC is simple. It includes an icon file GENERIC.ICO that was created with the 
SDKPaint application that comes with the Windows Software Development Kit. It also defines the program’s menu. 
Note that the menu items are given ID numbers, which are defined in the header file. 


© Listing 1-3. GENERIC.RC Resource File © 
/* generic.re 

#include <windows.h> 

Hinclude “generic.h" 


generic ICON generic.ico 
generic MENU 
BEGIN 
MENUITEM “&Do It!" IDM_DOIT 
MENUITEM "Quit", IDM_QUIT 
END 


The .DEF definition file provides the linker with information on how to assemble the finished program. Chapter 
14, Memory Management, contains a full discussion of all of the statements that can be put in definition files. Here is 
a brief description of this example file. 

The DESCRIPTION string is added into the file, usually to contain copyright information, EXETYPE of WINDOWS 
tells the linker that this will be a Windows 3.0 version program. The STUB line names a small file that ends up 
becoming the beginning of the finished program. The WINSTUR file is the code that prints out a warning message if a 
user tries to run a Windows program from DOS. | 

The CODE and DATA statements control how memory will be managed for this program. Listing 1. 4, shows the 
normal settings. HEAPSIZE and STACKSIZE control the amount of memory allocated for the program’s local data 
heap and stack. Finally, the EXPORTS section names all of the functions (besides the mandatory wae} that the 
program will want Windows to call. 


© Listing 1-4. GENERIC.DEF Definition File = 3 


NAME GENERIC 

DESCRIPTION "generic windows’ PLesram: 
EXETYPE WINDOWS 

STUB _  ‘WINSTUB.EXE' 

CODE PRELOAD MOVEABLE 

DATA. PRELOQAD MOVEABLE MULTIPLE 
HEAPSIZE 1024 

STACKSIZE 5120 

EXPORTS WndProc 


NMAKE.EXE is a program that runs other programs, typically compilers and linkers. NMAKE automates compila- 
~ tion of a program based on an NMAKE control file. The corvention is to name the NMAKE control file the same as the 
main C program, but without an extension. For example, the NMAKE file for GENERIC.C is GENERIC, shown in 
Listing 1.5. The GENERIC listing starts with the ALL statement. This tells NMAKE that we are trying to create 
GENERIC.EXE and that any file that has been saved more recently than GENERIC. EXE is going to need to be included - 
inthe next compilation. 

The next two lines define macros. Anytime the CFLAGS word is found preceded by a dollar sign and parentheses, 
the line of compiler switches “-c -D LINT_ARGS -A -Os -Gsw -W2” is substituted. These are the standard compiler 
switches for compiling a small Windows C program. Similarly, LFLAGS is replaced by /NOD, a linker control switch. 
These flags are discussed in Chapter 14 on memory management. 

The remaining lines tell NMAKE which files to compare to decide if a file needs to be recompiled. For example, if 
either GENERIC.C or GENERIC.H has been saved more recently than GENERIC.OBJ, the next line is executed. The 
resource compiler, RC.EXE is controlled by the next group of commands. The last group controls the linker. Note that 
RC is run again at the very end of the NMAKE file. The resource compiler adds the compiled resource data (from our 
resource file above) to the program file and then marks the completed program as a Windows 3. (version application. 


ve 
- 


rae 
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© Listing 1-6. GENERIC—The NMAKE File __ 
ALL: generic.exe ; . 


CFLAGS=~-c -D LINT_ARGS -AS =08 -Gsw -We 
LFLAGS=/NOD 


generic.obj : generic.c generic-h . 7 compile the c file 
$(CC) SCCFLAGS) generic.c : 


generic.res: generic.rc generic.ico 3; compile the resource file 
re -r generic.rc 


generic.exe : generic.obj generic.def generic.res ; link'm together 
Link SCLFLAGS) generic, , ,Libw slibcew, generic 
re generic.res 


The last file you have to create is the program’s icon. This is done using the SDKPaint application, choosing the 
icon file type. Save the icon you create as GENERIC.ICO. Once you have all of these files, you can create the working 
program by typing the command 


NMAKE GENERIC 


from within DOS. If you have not done all of this, I suggest you try it. The GENERIC application serves as the basis for 
most of the programming examples in the rest of the book. You can run the program by double-clicking the 
' GENERIC.EXE file name from within the file manager, or by using the “Program Run” menu item from the program 
manager, or i ping WIN GENERIC from the DOS command line. 


‘How Windows Programs Are Compiled and Linked 
~ Inaconventional C program, you build the program by first compiling all of the C language files and ign linking them 
to make the final executable file (an .EXE file in DOS). Windows works the same way, but with an added step: the 
resource compiler. One of the many clever aspects of the Windows environment is the separation of programming 
code (C code) from programming resources. In Windows, resources refer to things like menus, dialog box outlines, 
icons, bitmaps, and blocks of text. They are stored in a resource file, separate from the C language files. mesouree files 
are compiled using the resource compiler, RC.EXE. . 
If you look at the GENERIC.RC file, you will see that only two resources are included in this simple example. The 
first is the icon. The resource compiler reads the line 


generic ICON generic.ico 


and pulls in the icon data from the file GENERIC. ICO. The name “generic” on the left is then associated with the data 
from this file. 


Similarly the lines 7 
generic MENU 
BEGIN : 

MENUITEM “&Do It!" IDM_DOIT 


MENUITEM “&Quit", _IDM_QUIT 

END ae . . 

define a menu with two items (“Do It!” and “Quit”), which are associated with the menu item numbers IDM_DOIT and 
IDM_QUIT (defined in GENERIC.H). Given this simple definition, Windows knows to space the menu items along the 
menu line of the window, highlight the items when clicked with the mouse, etc. The only thing left for the programmer 
to worry about is what action to take when the menu items are activated. 
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The other added file needed for Windows programs is the definition file. GENERIC.DEF provides basic informa- 
tion about how to build the Windows program. For example, you specify the amount of memory to reserve for the 
program’s stack and free memory area, how memory is to be managed (MOVEABLE...), and the name of the functions 
that Windows will be passing messages to (EXPORTS...). We will discuss this file in the chapter on memory manage- 
ment functions. For now, just realize that a file like this is needed for every Windows program and that .DEF files tend 
to all be similar. The full sequence of events in the creation of the GENERIC.EXE program is as follows: 


GENERIC.C —> compiled by CL —> GENERIC.OBJ 
GENERIC.RC —> compiled by RC —> GENERIC.RES 
GENERIC.OBJ + GENERIC.RES + GENERIC.DEF —> linked by LINK and RC —> GENERIC. EXE 


The NMAKE file takes care of all of this for us, so that you only have to issue one command (NMAKE GENERIC) to 
create the complete program. 


How Windows Programs Work | 


If you check the file size of the GENERIC.EXE file, you will find that it is about 8200 bytes. This is remarkably small, 
considering that you have a resizeable graphics window, icon and menu functions built in, and full mouse support. The 
secret to this small size is that Windows programs do not contain even a fraction of the program code needed to do all 
. of these operations. The program you create makes uses of a large collection of functions that are part of the Windows 
environment when Windows is running on your computer. Every Windows program shares these working libraries of 
functions for control of the screen, printers, keyboard, mouse, menus, bitmaps, and a long list of other functions. 

This collection of working functions is maintained in files stored in the SYSTEM directory on your hard disk. The 
SYSTEM directory was created when you installed Windows. The three primary files are _ 


, ~ GDLEXE Video display and printer functions. 
USER.EXE Mouse, keyboard, sound, communications port and timer Support, 
KERNEL.EXE File and memory management. 


Each of these programs in turn calls driver files (like DISPLAY. DRV) for specific functions. Windows silly loads 
the modules it needs into memory and swaps them out of memory when they are no longer needed. Besides saving you, 
the programmer, from having to create sa of this logic every time you write a complete program, Windows also greatly 
reduces memory consumption. All of the® ‘application programs running at once share the same basic support library 
for the hardware. 

As we will see in Chapter 14, Memory Management, Windows does even more than this to conserve memory. If 
you write a large program with a number of C files linked together, Windows will load just the parts it needs to start up. 
Later, as the user makes use of other functions, Windows will load the other parts as needed. Windows will also move _ 
data and programs around in memory to make room for new material. All of this is transparent to the user. The bottom 
line is: Our little GENERIC.C program may not look like much in its raw C language form, but when it is operating as 
a running program, it has an army of Windows functions behind it. 


’ . 
Windows Naming Conventions—WINDOWS.H | 


Windows has a lot of functions. To minimize the chance of passing the wrong kind of data to a function, the developers 
of Windows developed a consistent naming convention so that the name of the variable indicates the type of data to 
which it refers. This system of names is often call “Hungarian notation” in honor of its inventor, Charles Simonyi. The 
basic system of prefixes is shown in Table 1-1. 


WINDOWS AP! BIBLE . 


b’ BOOL Lint use only TRUE and FALSE ai 1 and 0) 


by - BYTE (unsigned char) 
c: char 
, dw ~_ DWORD (doubles word, an unisigned long integer) 
fr function | . 
‘sg global (the author’s use of “g”) 
h handle (explained below) 
> - int (two byte integer) 
| , long 
n short (int) ornear pointer 
p pointer 
s | ~ string 
87 _ String terminated by zero 
Ww word (two bytes) 


Table 1-1. Variable name prefix codes used in Hungarian notation 


For example, the variable IpseBigName is a long pointer to a zera terminated string (1 = long, p = pointer, sz = 
zero terminated string). Also note the use of capital letters in the name to make the word breaks clear without 
wasting space. Extending this concept, Windows makes extensive use of the C Janguage preprocessor to create and 
use new data types, In many cases these data types are just another name for an integer or long variable. Using the 
Windows name, rather than the underlying data type, helps keep your program clear and reduces the chances of 
making a silly mistake. 

All of these typedefs and defines are ina large header file called WINDOWS.H. You can see a reference to this file 
. at the top of GENERIC.C and GENERIC.H. Every program you write under Windows will need this header file at the 
top, so that the compiler can keep track of all the preprocessor directives. Listing 1-6 provides a few examples from 
WINDOWS. H. 


ae Listing 1-6. WINDOWS.H Excerpt oct 8 


typedef 


POINT FAR 


typedef int BOOL; 
typedef unsigned char BYTE; 
typedef unsigned int WORD; 
_typedef unsigned long DWORD; 
‘typedef char near *PSTR; 
typedef char far “*LPSTR; 
‘typedef WORD HANDLE; 
typedef HANDLE HWND; 
typedef HANDLE HICON; 
typedef HANDLE HOC; 
typedef HANDLE HNENU; 
typedef HANDLE HFONT; 
_typedef struct tagPOINT | 
{ 
int .x; 
int. y; 
} POINT; 
typedef POINT *PPOINT; 
_ typedef POINT NEAR *NPPOINT; a 
*LPPOINT; 
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typedef struct tagRECT 
{ me 


int left; 

int top; 

int right; 

int. bottom; 
} RECT ; ‘ 
typedef RECT *PRECT; 
typedef RECT NEAR *NPRECT; 
typedef RECT FAR *LPRECT; 
ddefine WM_CREATE ~ Qx0001 
H#define WM_DESTROY : 0x0002 
H#define WM_MOVE 0x0003 
H#define WM_SIZE | 0x0004 


The first six lines in Listing 1-6 give shorthand names for common data types. This saves time by allowing you to 
use the word “BYTE” in place of “unsigned char” any time you declare a variable name. Note that the shorthand names 
follow the prefix rules. For example PSTR is a pointer to a string, while LPSTR is a long (far) pointer to a string. The 
next group of typedefs define “HANDLE” and then define a bunch of different handles for icons, menus, etc. If you 
trace the lineage of typedefs, you will realize that all of these handles are just unsigned ints. Windows uses them to 
keep track of all sorts of data in memory, including bitmaps, memory blocks, icons, logical brushes, etc. Handles are 
definitely NOT addresses in memory.-Just think of a handle as an ID value foradataitem. = . 

The third group in the example shows the creation of a new data types POINT and RECT for points and rectangles. 
In this case , the typedefs include the creation of structures to hold the x and y coordinates. Three pointer data types 
are then based on the data types. The handy thing about complex data types like these is that you can refer to all four 
- data points that define a rectangular area with a single variable name. The last group of defines in Listing 1-6 provides 

names for the numeric values of a series of Windows messages. These names make it a lot easier to read the program. 
A complete listing of WINDOWS.H is included at the end of this book. As you start procramnine in Windows, you will 
probably find yourself referring to this listing frequently. 


- Improving GENERIC 

If you try to resize the GENERIC program’ s window, you will notice that the “Ok, I did it!” message disappears every 
__ time you change the window’s size: That is because Windows repaints the center of the window (called the client 
area) every time a part of the window is changed or resized. 

To keep some text on the client area, we can retype it every time the window i is repainted. How do we know when 
Windows wants to refresh the screen? Simple, we just look for the WM_PAINT message in our WinProc() function. 
Listing 1-7 shows the WinProc() function for the modified GENERIC.C program. The changed portions are empha- 
sized. 


& Listing 1-7. GENERIC2. C—Changes to Process the WM_PAINT Message 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ . 


HDC : hDC ; , /* device context handle */ 
PAINTSTRUCT ‘ps; ie 
switch CiMessage) /* process windows messages */ 


case WM_PAINT: 
“Apc = BeginPaint(hwnd, &ps) ; 
TextOut Choc, 1, 1, 
“rtm here because of WM_PAINT.", 29) ; 
EndPaint ChWnd, &ps) ; 
Pe break ; ge gh Sy, 
case WM, _COMMAND: /* progess:menu items */ 
oe (wParam) ee te, 


-€ase IDM DOIT: ie User hit the “Do it" menu item */ 


WINDOWS AP! BIBLE: 


hDC = GetDC (hWnd) ; : 
TextOut (hDC,.10, 20, "OK, I did it!", 13) ; 
ReleaseDC (hWnd, hDC) ; ( 
< break ; 
case IDM_QUIT: 
Destroywindow Chifnd) : 
break ; 
} 
break ; 
case WM_DESTROY: 
PostQuitMessage (0) ; 
break ; 
default: 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
oy : 
return (OL) ; ; = 


Now when you run the GENERIC.EXE program, the window always shows the message “I’m here because of 
WM_PAINT.” This message persists after resizing the window, as it is repainted every time a WM_PAINT message is 
received. The result looks like Figure 1-3. The old message “Ok, I did it!” still appears if Jou click the “Do It!” menu 
item, but continues to disappear if you resize the window. 

Besides demonstrating how the WM_PAINT message is used, this example i is typical of how Windows programs 
are developed. You start with a simple outline such as GENERIC.C, then gradually add the functions you need for your 
specific application. The end results can be as different asa spreadsheet and com- : 

munications program. They all have their roots in the basic structure of 
GENERIC. C. 


Tig tfats. 


an ee earn Fegenene 
: I'm here because of WM_PAINT. 
Instances and Meacage Loops" 


We went over the code in GENERIC.(’s WinMain() function pretty fast. Although 
all of the functions used in WinMain() are discussed in more detail in later chap- 
ters, there are a few points worth noting here. You may have noticed that both Figure 1-3. The Improved . 
WinMain() and WndProc() are declared with the PASCAL statement. This savesa © GENERIC.C Processing the . 
~ few bytes when the compiler pushes the function’s parameters on the stack. The | WM_PAINT Messages. 
trade-off is that the PASCAL convention does not allow functions to have a variable ss 
number of parameters. Functions like printf() cannot use the PASCAL calling convéntion, as you do not know in 
advance how many parameters will be passed to the function. Windows 1 uses the PASCAL statement wherever possible 
to make the code as small and fast as possible. Ons; 

~ The WndProc() function is also preceded by the FAR statements. This makes the address of the function a FAR 
pointer. As Windows will use all available memory ii to hold programs, FAR pointers are needed for functions that 
Windows calls directly. 

The first two parameters passed by Windows t to WinMain() when the program sarin are hlnstance and 
hPrevinstance. These are “instance handles.” You can run more than one copy of a program at the same time under 
Windows. Each version of the program is called a “program instance.” Windows keeps only one copy of the program’s 
code in memory, but keeps separate data for each instance. 

GENERIC.C’s WinMain() function stores the instance handle | in a global variable ‘ghInstance, defined in 
GENERIC.H. This is done because the instance handle is frequently needed in calling other functions, and it saves a 
little time if you keep a copy of the handle. If the program is starting for the first time (no other copy is running), the 
hPrevInstance will be NULL (zero). If another copy is running, hPrevInstance will be an integer value. GENERIC.C 
checks this and does not bother trying to register the window class for the program if another instance exists. That i is 
because the first instance of the program will have already registered the class. 

WinMain() passes two other parameters. nCmdLine is a pointer to a null- terminated character string containing 
the command line that launched the program. You can set the command line from within the program manager using 
the “File/Properties” menu item, This is rarely used in Windows. Windows programs tend to use initialization files 
such as WIN.INI to pass data to the application on startup. Support for initialization files is discussed in Chapter 20) : 
MS DOS and Disk File Access. 
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The »CmadShow parameter is an integer. This value is passed to the ShowWindow() function later in WinMain() 
to control the initial appearance of the window. You do not have to use this value with ShowWindow(). The 
ShowWindow() function description i in Chapter 3 discusses other options, such as starting the window ina minimized 
(iconic) state. a 

The WindProc() function also has four parameters. hWnd is the handle of the window receiving messages from 
Windows. Windows maintains a list of all windows in memory, using the handle (an unsigned integer) as an index. We 
will use this handle to refer to the window in many functions. 

iMessage is the message from Windows. This is an unsigned integer, usually referred to by the symbolic name 
defined in WINDOWS.H, such as WM_PAINT. The “WM” stands for Windows Message. The wParam and lParam 
parameters are data that are passed along with each message. wParam is a WORD (two bytes), while [Param is a 
LONG value (four bytes). Their meaning will depend on the message being sent. For example, if you change the size of 
a window, Windows will send a WM_SIZE message. With this message, [Param will hold the new height and width of 
the window after resizing. [Param and wParam have different meanings with every Windows message. 

In the simple GENERIC example, only a few Windows messages are acted on by the WndProc() function. The rest 
of the messages fall through to the bottom of WndProc() and end up sent to DefWindowProc(). This function does the 
default actions for all Windows messages. Default actions are things like processing WM_SIZE messages to change the 
window’s size. You can stop the default action from occurring by intercepting the message in the WndProc().function, 
and then just returning zero from WndProc(), rather than passing the message on to DefWindowProc(). More on this 
in Chapter 8, Message Processing Functions. 


Program Listing Conventions In This Book 


The GENERIC application described above forms the basis for every example in this book. To save space, repeated 
portions of the program listings are not shown unless some change must be made. In most cases, the only changes are 
to the WndProc() function. If the example listing shows only the WndProc() function, you can assume that WinMain() 
and the support files (GENERIC, GENERIC.H, GENERIC.DEF, GENERIC.RC) are all identical to those listed in this 
chapter. 

You will also note the use of two global variables in many of the examples. ghJnstance and gszAppName are 
defined in GENERIC.H. They contain the program’s instance handle and program name, respectively. The instance 
handle and application name are used in many different function calls. You can easily write code that avoids the use 
of these global variables. They are used in the examples to save space and improve clarity. 

One final space saving trick is used in simple examples where only the top few lines of WndProc() are used to 
demonstrate a function. If the rest of WndProc() is agenlical to the GENERIC.C , the bottom oe is replaced with: 
[Other program lines]. 
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Usually the word “window” brings to mind the application program’s full client area, frame, menu, and caption bar. It 
turns out that Windows uses the same low-level logic to control all sorts of similar objects, including windows, buttons, 
list boxes and scroll bars. All of these are forms of “windows.” They are all created using the CreateWindow() function. 
The main elements of a window are illustrated in Figure 2.1. . 

CreateWindow() is the most complex function in Windows. It is so complex because this one function can create 
a wide range of objects. Within each family of objects, such as scroll bars and buttons, there are a range of options. 
These options give you control over what the object looks like, where the text goes, if lists are sorted, and so on. The 
different options are given names in the WINDOWS.H file. In many cases, you can use several of the options at once, 
combining their effects. For example, a list box control, where you want the contents sorted and the parent window 


notified of any selections, would have the series of Windows styles 
LBS_NOTIFY | LBS_SORT Minimize 
& ' 
Maximize 

a Btns. 


The C language binary OR operator (I) combines System 
these binary values before they are passed to the bade 
CreateWindow() function. 

The other important control over a window is the 
_ window class upon which it is based. There are two basic + Menu 


choices here: Use an existing window class such as “BUT- iad (The Client Area) 
TON” or the parent window’s base class, or create a new 

‘class from scratch. We will look at an example using both Frame 
methods in the next two sections.. alt Figure 2-1. Elements of a Window. 


Using CreateWindow() Based on an Existing Class 
Let’s modify the GENERIC.C application to show some window types in the program’s client area (the work area 
below the menu bar). The only changes will be in the WinProc() function. We will put in four calls to CreateWindow(), 
making button, static text, edit, and scroll bar “windows” when the user clicks the “Do It!” menu item. 


C> Listing 2-1. Creating Different Windows Using the Same Base Class 
long FAR PASCAL WndProc. CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
t 


HWND hButton, hStaticText, hEdit, hScrotl ; 
switch (iMessage) /* process windows messages */ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) : 
{ Pay 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
i oe /* create and show a button */ 
hButton = CreateWindow ("BUTTON", "Button", 
WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON, 
: 10, 10,-100, 40, hWnd, CHAE Ts ghInstance, NULL) ; 
ShowWindow hButton, SW_. SHOW) ; 
/* create and show static text */ 
hStaticText = CreateWindow C"STATIC", "Static Text", 
WS_CHILD ¥ WS. VISIBLE | BS _PUSHBUTTON, 
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150, 10, 100, 15, hWnd, CHILD2, ghInstance, NULL) ; 
ShowWindow (hStaticText, SW_SHOW). ; 
/* create and show an edit control */ 
hEdit = CreateWindow ("EDIT", "Edit Me", 
WS_CHILD {| WS_VISIBLE | WS_BORDER, : 
150, 40, 100, 25, hWnd, CHILD3, ghInstance, NULL) ; 
ShowWindow (hEdit, SW_SHOW) ; 
/* create and show a scroll bar */ 
hScrotl = CreateWindow ("SCROLLBAR", "", 
WS_CHILD | WS_VISIBLE | SBS_HORZ, 
10, 100, 200, 20, hWnd, CHILD4, ghInstance, NULL) ; 
ShowWindow (hScroll, SW_SHOW) ; 
break ; . 


[Other program lines] , s 


The rest of the program is the same as GENERIC.C) 

The button, scroll bar, static text, and edit controls are all called “child window controls.” The word “control” 
means that they were created with a predefined window class such as BUTTON, rather than registering a new window 
class. They are child windows because each is related to the parent window and will only be shown if the parent is 
visible. The WS_CHILD flag used in each call to CreateWindow() creates child windows. CreateWindow() was also passed 
the parent window's handle kWnd. This allows CreateWindow() to make the correct linkup of child and parent. 

Notice that the first parameter in each of the calls to CreateWindow() is a word that specifies the type of child 
window control being created: BUTTON, STATIC, EDIT, and SCROLLBAR. The second parameter is the text string 
that will show up inside the control. Scroll bars do not have text, so a null string (“”) is included. The series of 
numbers, such as “10, 10, 100, 40”, sets the size and location of the child window. The parameter third from the last is 
the ID value for the window. In this case, the four controls have been numbered in sequence CHILD1, CHILD2, 
CHILD3, CHILD4. These values are normally defined in the program’s header file 


‘define CHILD1 100 
H#define CHILD2 101 
#define CHILD3 102 


Also note that the program’s instance handle (saved as the global variable ghlnstance) is passed to Create- 
Window(). 
When you compile and run this program, clicking the 
' “Do It!” button results in a screen like that shown in Fig- 
ure 2-2. Experienced programmers will note that this ex- 
ample looks like a dialog box (the subject of Chapter 13). 
Static Text However, this is a normal window containing child win- 
dow controls. ne 
When you resize this window, the child windows in 
the client area are automatically redrawn. This is a big , 
- improvement over our GENERIC.C program in Chapter 
1, where we had to explicitly redraw the text every time a 
WM_PAINT message was received. We have taken advan- © 
tage of Windows’ built in iogic for child windows. Win- - 
: ~ dows keeps track of child windows and upoateest them 
Figure 2-2. Four Types of Child Window Controls. along with their parent. 
; ‘If you click the “Edit Me” edit control with the 
mouse, a beam cursor (caret) appears in the control, and you can type in new letters, backspace to delete, etc. There 
is a lot of built-in logic in the edit control, which saves the programmer from doing a bunch of mundane code. You can 
create a serviceable text editor with nothing more than a large edit control. Edit controls are covered in more detail 
in Chapter 9, Windows Messages. 
The example in Lisitng 2-1 does not do anything when you click one of the four controls. If you want to use the 
button control in a real program, you will need to process the messages Windows generates. If you click the button 


Ke 
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control with the mouse, Windows sends a WM_COMMAND with wParam equal to the ID value of the control. A code 
fragment for this type of processing might look like Listing 2-2. 


& Listing 2-2. Example Code for Recognizing Button Controls 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


t 


switch (iMessage) , /* process windows messages */ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) fed 


case CHILD1: /* control 1 pressed */ 
/* do something here */ 
break ; 

case CHILD2: /* control 2 pressed */ 
/* etc. */ 


[Other program lines] 


This simple interception of WM_COMMAND messages is typically used for buttons. For more complex controls 

such as the scroll bar and edit controls, a number of messages are possible, depending on what the user does with the 

-control. Scroll bars are the subject of Chapter 5. Edit controls are discussed in Chapter 9 under the EM and EN 
message section (Edit Message and Edit Notify). 


Creating New Window Classes with Separate Message Processing ae 


The previous example used four of the predefined control classes to create child window controls. We can also create 
child windows that are complete windows, including menus, captions, minimize and maximize boxes, etc. The child 
window becomes its own “little world” and can display information and process Windows messages independently 
from its parent window. The best way to deal with more complicated child windows is to give them their own message 
processing function. This allows you to break up your program 
logic into a set of similar message processing functions, each 
-modeled after WinProc(). 
To show how child windows can process their own mes- 
sages, let’s create a program that looks like Figure 2-3. The 
~ WINDEXM2 program’s main window will be identical to the. . 
GENERIC.C program from Chapter 1. In the client area we will 
put a child window. The child window will be builtfromasepa- | 
rate window class, and have its own message processing func- _ OR at A Pan aus 
tion to deal with screen updates, etc. . icant tes 
Creating this program will require modifications to a, M INT in C hil 
eral parts of the GENERIC.C application. It is best to make a 
copy of all the GENERIC.* files and then modify each of them. 
WINDEXM2.C. (Listing 2-3) has an identical WinMain() 
function to GENERIC.C. In the WinProc() function, WIN- 
DEXM2 picks up the WM_CREATE message that Windows 
sends when a program is started. When this message is re- 
ceived, WINDEXM2 creates a new window class called | 
“SecondClass.” This class has several changes compared to the 
base class we used to create the WINDEXM2 window. The fol- 
lowing line sets the mesa? processing function equal to. Figure 2-8. WINDEXM2—A Child Window with. 
“ChildProc.” ~... | : & olhe 2 - Separate Message Ce 


wndcLlass. LpfnWndProc = ChildProc ; 


This function is shown at the bottom of WINDEXM2.C. The class also uses a different cursor shape than the base 
window class because we specified the predefined IDC_CROSS" cursor shape. Similarly, a predefined “brush” used to . 


4 0 | | 


2. CREATING WINDOWS V 


paint the background color LTGRAY_BRUSH is loaded using the GetStockObject() function. Stock objects are pens 
and brushes that are always available in Windows. Chapter 11, Painting g the Screens, explores creating custom pens 
and brushes. Chapter 6 covers cursors. 


wndclass.hCursor 
wndclass.hbrBackground 


LoadCursor (NULL, IDC_CROSS) ; 
GetStockObject (LTGRAY_BRUSH) ; 


The changes to the cursor and background brush mean that any time a window is created from the “SecondClass” 
window class, the mouse will switch to a cross shape in the child window's area and the background will be painted 
light gray. . 
© Listing 2-3. WINDEXM2.C 


/* windexm2.c example of creating a child window with message processing */ 


Hinclude <windows.h> /* window's header file - always included */ 
Hinclude "windexm2.h" /* the application's header file */ 


int PASCAL WinMain CHANDLE hInstance, HANDLE hPrevInstance, LPSTR lpszCmdLine, 
int nCmdShow) 


{ . 
/* Exactly the same as WinMain() in generic.c —- chapter 1 */ 
} i 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ ‘ 
HDC hoc ; /* device context handle */ 
Static WNDCLASS wndclass ; . /* the window class */ 
static HWND hListBox ; /* the window handle */ 
switch CiMessage) /* process windows messages */ 
{ 


"case WM_CREATE: /* build child window when program starts */, 
wndclass.style = CS_HREDRAW | CS_VREDRAW | 
CS_PARENTDC ; 


wndélses.ipiaundProe ChildProc ; 


wndclass.cbClsExtra 0:5 
wndclass.cbWndExtra 0; 
wndclass.hInstance ghInstance ; 
wndclass.hicon NULL ; 


LoadCursor (NULL, IDC_CROSS) ; 
GetStockObject (LTGRAY_BRUSH) ; 


wndclass.hCursor 
wundclass.hbrBackground 
wndclass.lpszMenuName NULL ; 
wndclass.lpszClassName “SecondClass" ; 

/* register the window class */ 
if(RegisterClass (&wndclass)) 


tuk uu tou ou 


{ : 
hListBox = CreateWindow ("SecondClass", "Child Window", 
WS_CHILD | WS_VISIBLE | WS_BORDER | WS_ CAP ae Nae 
10, 50, 200, 150, hWnd, NULL, au pexae cee NULL) ; 
ShowWindow ChLi stBox, SW_. SHOW) ; 
+ 2 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: : /* User hit the “Do it" menu item */ 
hDC = GetDC ChWnd) ; /* get device Context bats 
TextOut ChDC, 10, 20, sone I did it!", 13) ; 
Releasede ChWnd, ADC) ; /* release device ‘context x] 
break ; 
case IDM_QUIT: /*. SO: appl ecation oe 
bestroyWindow ChWnd) ; 
break ; 
} j 


{ 


‘ 
1 


{ 
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: break ; 
pone - case WM_DESTROY: 
. PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam; lParam) ; 
} ae : 
return (OL) ; 


/* Here is a separate message processing procedure for the child window */ 


Long FAR PASCAL ChildProc (HWND hWnd, unsigned iMessage, HORE pana 
LONG lParam) 


; 
HDC hoe ; /* device context handle */ 
PAINTSTRUCT ps ; /* paint structure */ 
switch (iMessage) k /* process windows messages xf 
C 
case WM_PAINT: /* just write in the window */ 
hDC = BeginPaint(hwWnd, &ps) ; 
TextOut (hDC, 1, 1, “WM_! PAINT in Child.", 18) ; 
EndPaint (hWnd, &ps) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; ‘ 
} 
return COL) ; 
} 


The function ChildProc() at the end of Listing 2-3 looks similar to the WinProc() function from GENERIC.C. Any 
message processing for our child window will be handled in this function. In this example, all we do is put some text 
into the window every time a WM_PAINT message is received. We have to make a couple of other changes to files to 
get all of this to work. One simple thing is to add the function prototype for ChildProc() to our header file so that the 
compiler can figure out what data types are used. WINEXM2.H is shown i in Listing 2-4. 


© Listing 2-4. WINEXM2.H Header as 


/* windexm2.h */ 


#define IDM_DOIT 1 Oo - 7 menu item id values */ 
#define IDM_QUIT 2 me 


/* gtobal variables */ 
int ghInstahce ; : ae, 
char gszAppName CJ= “Windexm2" ; : 


/* function prototypes */ 
long FAR PASCAL WndProc CHWND, dna taneas WORD, LONG) ; 
tong FAR PASCAL ChildProc CHWND, unsigned, WORD, LONG) 2 


The other change is to put a reference to ChildProc() in our definition file, such as where shown in Listing 2-5. 
This is needed only when the function will be accessed directly by Windows, processing Windows messages. That’s 
exactly what ChildProc() does, so it is important not to forget to add it to the .DEF file. Details on .DEF files are 
covered in Chapter 13, Dialog Boxes. 


© Listing 2-5. WINDEXM2.DEF Definition File 


NAME WINDEXN2 

DESCRIPTION ‘create windows example’. 
EXETYPE WINDOWS vars 

STUB. "WINSTUB.EXE' 

CODE PRELOAD MOVEABLE 

DATA PRELOAD MOVEABLE MULTIPLE : 


HEAPSIZE -— 1024 
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“STACKSIZE 5120 
EXPORTS. WndProc 
ChitdProc 
Ifyou compile WINDEXM2.C and try it, you will notice that the child window is updated (painted) automatically 
whenever the parent window is resized. The child window has a gray client area (from the class definition), and the 
' cursor changes from the normal arrow to a cross shape when it is within the child window's bounds. 


Messages Generated by CreateWindow() 


In WINDEXM2.C, the WndProc() function processes the WM_CREATE message. It is at this point that WndProc() 
creates-the child window. Where did WM_CREATE come from? It turns out that Windows sends five messages to 
WndProc() when the program’s main window is created by calling CreateWindow() in WinMain(). WINDEXM2.C 
chooses to act on one of them, WM_CREATE, but just passes the other four on to DefWindowProc(). Windows knows 
to send the messages to WndProc(), as that was the name of the window message processing function specified in the 
class definition for the program’s main window. We also included WndProc() in the EXPORTS section of the program’s 
.DEF definition file, so that Windows would have the full address. 

The sequence of messages that are generated by CreateWindow() is shown in Table 2-1. The actions described for 
each message are taken care of by the DefWindowProc() function at the bottom of WndProc(). You can get an idea of 
how important DefWindowProc() is from the complexity of these actions. Fortunately, DefWindowProc() comes with 
Windows, so we can take advantage of all of these built-in features without any extra coding. 


WM_GETMINMAXINFO Determines the size and position of the window. 


WM_NCCREATE Window nonclient area about to be created. Memory for the window is allocated internally by 
Windows. Scroll bars are initialized. 

WM_NCCALCSIZE Calculation of the window’s client area and scroll bar positions. 

WM_CREATE Notification that a window is about to be created. 

WM_SHOWWINDOW Display the window. 


Table 2-1. Messages Generated by CreateWindow(). 


An interesting point to mention here is the order of exectiiun of aitftezent parts of the WINDEXM2 program. If you 
get into the CodeView For Windows debugger and set a few Uree'psints, ;ou will find that the five messages are 
processed by WndProc() right after CreateWindovw() is called and before the next linc in WinMain() is executed. 

This behavior is completely different from a C program running under DOS. Under DOS you can expect one 
program line to be executed right after the previous one. Windows programs are different. Windows sends messages to 
WndProc() when Windows feels like it, not necessarily when you might expect it. Function calls within WndProc() 
may also generate messages that in turn are processed by WndProc(). Message processing functions such as 
WndProc() are said to be “reentrant,” as they may be called many times in a single logical activity. More on this in 
Chapter 8, Message Processing Functions. 


Other Uses for Window Controls rv 

In the function description for CreateWindow() that follows, there is a long table of window styles. There are so many 
window styles available that it is difficult to keep track of them all. Here are a few unusual ones that might come in 
handy. 

The static class is normally used to display text on ajwindow. Using the static ee is more convenient than 
repainting the text every time a WM_PAINT message comes along because the static window class is automatically 
redrawn. Some of the options for the static class allow items other than text. The SS_BLACKRECT style fills the region 
with the system color for the edge ef windows (usually black). Similarly, SS_GRAYRECT and SS_WHITERECT fill 
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rectangles with the screen (desktop) background and window background colors (defaults are gray and white). You 
can use a series of these controls to shade areas of your window's client area, again with automatic updating. - 

If you use an ampersand character (&) in a button class, the letter after the & will be underlined. Windows then 
uses this letter as an accelerator key. Pressing that letter on the keyboard is equivalent to moving to the button with 
the mouse. If you need to display & characters in a window style, disable the accelerator functions by using the 
SS_NOPREFIX style, or use a double && in the text string. 

The scroll bar class has a couple of styles that are handy if you want to have the scroll bar along one of the sides of 
the client area—typical for a word. processing application. The SBS_BOTTOMALIGN, SBS_TOPALIGN, 
SBS_RIGHTALIGN, and SBS_LEFTALIGN styles all fit the scroll bar to the parent window's client area, usiiig the 
default scroll bar width. More on this in Chapter 5, Scroll Bars. 

Ifyou want to have an icon on your parent window to pretty things up, there is an SS_ ICON style for the static 
class. This wil] save you from having to use Drawlcon() on every WM_PAINT cycle. You can also create your own 
custom buttor: % vsing bitmaps or painting on the button’s client area by using the BS_OWNERDRAW button stile. You 
will heve to crs... images for not only the button in its normal state, but also for an inverted image reflecting being 
pressed anit di abled (no input focus) state. See the owner-drawn menu example in Chapter 4 for an example of 
; processin,; {''» tae-sages for owner-drawn items. ; 


Function ce: criptions 
Table 2-2 su:imarizes the three window creation functions. The detailed descriptions follow. 


“Functis: === Purpose 


Neely | we 


Cresievnrsinw() Creates new windows and child window controls. 


Creaieviisic towEx() Creates new windows with an extended styie. 
RogisterClass() Creates new windows classes. 


Table 2-2. Functions for Creating Windows and Controls. 


CREATEWINDOW | 7 BWin2.0 eWin30 e@Win3l 
- Purpose — | Creates new windows and child window controls. 
Syntax . HWND CreateWindow(LPSTR (pClassName, LPSTR lpWindowName, DWORD dwStyle, int X, 
int Y, intnWidth, intnHeight, HWND hWndParent, HMENU hMenu, HANDLE hfnstance, LPSTR 
lpParam); 
Description CreateWindow() builds a window based on a window class created with RegisterClass() or based 


on a predefined contro! class. The location, size, and style of window are passed to CreateWin- 
dow() as parameters. ShowWindow() is used after the windows is created to display it on the 
screen. 


Uses The CreateWindow function is used both in the WinMain() function to create the application’s 
main window and also within the program to create child einicows and child window controls 
_ such as buttons and scroll bars. 


Returns HWND, a handle to the window created. The handle is a unique identifier for the particular win- 
dow or control created with each call to CreateWindow(). 
See Also RegisterClass(), ShowWindow(), DestroyWindow(), CreateWindowEx() 
Parameters ; . ‘ 
_ dpClassName —_—_ LPSTR: Pointer toa null-terminated string which contains the name of the window class. Classes 


’ can either be created using RegisterClass(), or they can be chosen from one of the predefined 
control classes described in Table 2-3. The class names are case sensitive. 


\ 
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Class Meaning | ; - . & 


‘BUTTON A rectangular push button control. 

COMBOBOX Combination of a list box, with an edit field on top. 

EDIT Rectangular region where the user can enter and edit text. . 

LISTBOX Alist of character strings. If the list length overflows the length of the box, a vertical scroll control will automati- 


cally appear on the right hand side. The listbox can contain graphics items, if the LB OWNERDRAWFIXED or 
LBOWNERDRAWVARIABLE styles are used. See Chapter 9, Windows Messages. 


MDICLIENT “A Multiple Document Interface window. This style is used for multiple overlapping child windows within the 
parent window's client area. See Chapter 29, Multiple Document interface. 


SCROLLBAR —_A scroll bar control. 


STATIC Static text. This style is used to place text on the parent window. 
Table 2-3. Predefined Windows Control Classes. 


lpWindowName — LPSTR: Points toa null-terminated character string that contains the window's name. For BUT- 


TON styles this string becomes the button’s text. For EDIT and STATIC styles the string is shown 
in the center of the control. For popup windows it is used as the title. 


dwStyle DWORD: Determines the style of window. The styles can be combined by using: the C language — 


be 


x 


binary OR operator. For example: WS_CHILD | WS_HSCROLL. Styles can be any of those listedin - 
Table 2-4. 

int: The horizontal position of the upper left corner of the child window orlcantrol You can use 
CW_USEDEFAULT to let Windows decide where to put a program’s window. 

The X,Y location is from the upper left corner of the screen or parent window client area tae 
child windows), measured in pixels (device units). 

int: The vertical position of the upper left corner or the child window or control. You can use 
CW_USEDEFAULT to let Windows decide where to put a program’s window. 


- nWidth int: The horizontal size of the window or control. You can use CW_U SEDEFAULT tolet Windows . 


decide what size to make a program’s window. 
The width and height are measured in device units (pixels). 


nHeight int: The horizontal size of the window or control. You can use CW_’ USEDEFAULT to let Windows 


decide what size to make a program’s window. 


hWndParent ~° HWND: Ahandle to the window’s parent. Specifv NULL if there is no parent window. In this case 


the window will not be destroyed automatically when the main aia window is destroyed. Use 
DestroyWindow() to remove a window from memory. 


hMenu HMENU: A handle to the window’s menu. NULL if the class menu is to be used. Use the dwStyle 


parameter to add or eliminate a menu from child windows. 


For controls, hMenu is used to set an integer ID value. This value will be passed as the wParam 
parameter of a WM_COMMAND message when the control is activated by a mouse click or key- 
press, 


hInstance ° HANDLE: The instance frandle for the program module creating the windows. 
lpParam LPSTR: A long pointer to a data structure passed to the window. For example the MDI (Multiple 


Document Interface) style passes the CLIENTCREATESTRUCT data here. Noma set to NULL, 
meaning that no data is passed via CreateWindow(). 


Related Messages WM_PARENTNOTIFY , WM_NCCREATE, WM_CREATE 


WINUVOUOWS API BIBLE 


Example 


zr 


This ene shows the creation of a pushbutton control. The button will hae the text “Press 
Me” in the center. The upper left corner of the button will be at 10,10 rélative to the upper left 


_ corner of the client area. The button will be 100 pixels wide and 40 high. The parent window’s 


_ handle is hWnd, and has an instance handle of hInstance. The button has an ID value of 101. 


Creating a window does not make it visible; the ShowWindow() does. 
HWND hButton ; 


hButton = CreateWindow ("“BUTTON", "Press Me", 
WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON, 
10, 10, 100, 40, hWnd, 101, hInstance, NULL) ; 
ShowWindow (hButton, SW_SHOW) ; : 


Table 2-4 summarizes all of the values that can be used in the dwstyle parameter. 


Button Styles 


Meaning | 


BS_AUTOCHECKBOX Small rectangular button with text to the right. The actansls can aitick be open or 


checked. This style toggles automatically between checked and open. 


BS_AUTORADIOBUTTON . Small circular button with text to the right. The circle can either be filled or open. This style 


BS_AUTOSSTATE 


BS_CHECKBOX 


toggles automatically between checked and open. 


Small rectangular button with text to the right. The button can either be filled, grayed, or 
open. This style toggles automatically between checked, grayed, and open. 


Small rectangular button with text to the right. The rectangle can either be open or 
_ checked. 


BS_DEFPUSHBUTTON Button with text in the center and with a defined (dark) border. This is the button that is 


BS_GROUPBOX 
BS_LEFTTEXT 


BS_OWNERDRAW — 


BS_PUSHBUTTON 
BS_RADIOBUTTON 
BS_8STATE 


pressed when the user presses the (ENTER) key. There can be only orfé DEFPUSH- 
‘BUTTON on a window. 


A box outline with text at the upper left. Used to group other controls. 
Causes text to be on the left side of the button. Use this with other button styles. 


Designates a button that will be drawn by the program. Windows sends messages to 
request paint, invert, and disable. Use this style for custom button controls. See the ex-- 
ample in Chapter 4 on owner-drawn menu items. 


A rectangular button with text in the center. 
Small circular button with text to the right. The circle can either be fi led or open. 


Smail rectangular button with text to the right. The button can either be filled, grayed, , 
_ Or open. 


Combo Box Styles 


CBS_AUTOHSCROLL Combo box control. This is a list box with an edit control at the top to display the current 


selection. Chapter 9, Window Messages, includes a combo box example and message 
descriptions. With the CBS_AUTOHSCROLL style, the edit area at the top automatically 
scrolls when typing fills the edit box. 


CBS_DISABLENOSCROLL (Win3.1) The list box of the combo box contro! shows a disabled vertical scroll bar when the list box 


‘CBS_DROPDOWN 


does not contain enough items to fil the list box window. Without this style, the scroll bar 
disappears when there are not enough items, 


Combo box control with a drop down scroll area. This reduces the space taken by the 
combo box when the list is not needed. 
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CBS_DROPDOWNLIST 
CBS_HASSTRINGS 


CBS_OEMCONVERT 


CBS_OWNERDRAWFIXED 


CBS_OWNERDRAWVARIABLE 


CBS_SIMPLE 
CBS_SORT 


Dialog Box Styles © 
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Combo box contro! with a drop down scroll area. The edit area at top is a static text item 


which only displays the current selection in the list box. 


The combo box control maintains the list box strings in memory. Fetch them by sending a 
CB_GETLBTEXT message. 


Combo box edit text is converted to OEM character set and then back to ANSI. Useful for 
lists of file names. 


An owner-drawn combo box. The combo box items are of fixed height. See the combo 
box example in Chapter 9, Window Messages, for an example owner-drawn combo box. 


An owner-drawn combo box. The combo box items can be of different heights. 
The combo box has a list box that is displayed at all times. 
The combo box items are sorted automatically. 


DS_LOCALEDIT 
DS_MODALFRAME 


DS_NOIDLEMSG 


DS_SYSMODAL 


Edit Control Styles 


Forces all memory used by dialog boxes into the application’s data segment. 


Creates a dialog box with a modal frame. Note that this can be combined with the 
WS_CAPTION and WS_SYSMENU styles. 


“No WM_ENTERIDLE messages are sent from the dialog box if created with this style. 


Normally, WM_ENTERIDLE messages are used to alert the application that the dialog box 
is displayed, but no user activity has happened yet. 


System modal dialog box. No other window can gain the input focus until this style dialog 
box is closed. Used for serious error messages. 


ES_AUTOHSCROLL 
ES_AUTOVSCROLL 


ES_CENTER 
ES_LEFT 
ES_LOWERCASE 
ES_MULTILINE 


ES_NOHIDESEL 
ES_OEMCONVERT 
ES_PASSWORD 


ES_READONLY (Win 3.1) 
ES_RIGHT 
ES_UPPERCASE 


Edit control with automatic horizontal scrolling if the text will not fit within the edit box. 


Automatic vertical scrolling for an edit control. Used with ES_MULTILINE. See the ex- 
ample in Chapter 9 of a multiline edit control with a vertical scroll bar. 


Text is centered within the edit control. 
Text is left-aligned within the edit control. 
All characters within the edit contro! are converted to lowercase as they are entered. 


Allows multiple lines of input within an edit control. This type of control provides basic text 
processing functions. The discussion of edit contre! messages that work with this control 
style is in Chapter 9. 


Edit control where the text is left unchanged when the control loses the input focus. 


Edit control text is converted to OEM character set and then back to ANSI. Useful for file 
names. 


Displays typed-in letters as astersik characters “*”. The actual typed letters are stored by 
the edit control. See the EM_SETPASSWORDCHAR message description in Chapter 9. 


The edit text can be viewed, but not changed by the user. 
Right-aligned letters within the edit control. 
All characters within the edit control are converted to uppercase as they are entered. 
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List Box Styles - 


LBS_DISABLENOSCROLL (Win 3.1) 


LBS_EXTENDEDSEL 
| LBS_HASSTRINGS 

LBS, MULTICOLUMAN 

LBS MULTIPLESEL 
LBS_NOINTEGRALHEIGHT 
LBS NOREDRAW 


LBS_NOTIFY 


LBS_OWNERDRAWFIXED 


LBS_OWNERDRAWVARIABLE 


» LBS_SORT: 
LBS_STANDARD 


LBS_USETABSTOPS 


LBS. WANTKEYBOARDINPUT 


The list box contro! shows a disabled vertical scroll bar when the list box does not contain 
enough items to fill the list box window. Without this style, the scroll bar disacpears when 
there are not enough items. ; : 
List box control where more than one ic can be selected by using the mouse and the 
shift key. 


List box control containing lists of strings. Send the LB_GETTEXT message to retrieve the 


"strings. - 


List box with multiple columns. Can be scrolled horizontally and vertically. Send 
LB_SETCOLUMNWIDTH to set the column widths. 


Any number of strings can be selected within the list box. Selection by mouse clicking, 
deselection by double-clicking. 


- Alist box of fixed size. The list box height is not scaled to match an even number of items 


(the default case). 


Alist box which is not automatically redrawn. Convert the control back to normal by send- 
ing the WM_SETREDRAW message. 

A list box that sends the parent window messages when the user selects one or more 
items. The list box messages are discussed in Chapter 9. 


A list box where the program is responsible for drawing all items. Items are of fixed vertical 
size. There is a similar example using an owner-drawn combo box in Chapter 9, Windows 
Messages. 


A list box where the program is responsible for fais all items. tems can be of different 
vertical sizes. ‘ 


A list box where the items are maintained in sort order. 


A list box containing Stings, automatically sorted, with messages sent to the parent win- 
dow when selections are made. 

A list box that recognizes and expands tab characters. By default, tabs are every eight 
spaces, See the EM_SETTABSTOPS message to change this value. . 


The parent window receives WM_VKEYTOITEM and WM_CHARTOITEM messages from 
the list box when it has the input focus and ee are pressed. Handy for setting key 


_ combinations. 


SBS_BOTTOMALIGN 


SBS_HORZ - 
SBS_LEFTALIGN 


SBS_RIGHTALIGN 


SBS. SIZEBOX. 


A scroll bar control, aligned with the bottom edge of the rectangle specified by the X, Y, 
nWiath, and nHeight parameters used in calling CreateWindow() for the parent window. 


‘The default scroll bar height is used. 


A horizontal scroll bar control. ; / 


-  Ascroll bar control, aligned with the left edge of the rectangle specified by thex, Y, nWiath, 
- and nHeight parameters used in calling CreateWindow() for the ee wna: The de- 


fault scroll bar width is used. 
A scroll bar control, aligned with the right edge of the rectangle specified by the x, Y, 


~ nWidth, and nHeight parameters used i in calling CreateWindow() for the parent window. 


The default scroll bar width i is used. 


Ascroll bar size box control. This is a small box that allows sizing of a window from one, 


location. 


‘ 
= 
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SBS_SIZEBOXBOTTOMRIGHTALIGN 


SBS_SIZEBOXTOPLEFTALIGN 


SBS_TOPALIGN 


SBS_VERT 
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Used with the SBS_SIZEBOX style. A size box control, aligned with the lower right edge of 
the rectangle ‘specified by the X, Y, nWidth, and nHeight parameters used in calling 
CreateWindow() for the parent window. The default size box size is used. 

Used with the SBS_SIZEBOX style. A size box control, aligned with the top left edge of the . 
rectangle specified by the X, Y, nWidth, and nHeight parameters used in calling 
CreateWindow() for the parent window. The default size box size is used. 

Used with the SBS_HORZ style. Puts the scroll bar at the top of the parent window's client 
area. , 


A vertical scroll bar control. 


Static Control Styies ee aed eee nn ee x] 


SS_BLACKFRAME 
SS_BLACKRECT 


‘SS_CENTER 
SS_GRAYFRAME 


SS_GRAYRECT 


SS_ICON 

SS_LEFT 
SS_LEFTNOWORDWRAP 
SS_NOPREFIX 
SS_RIGHT 

SS_SIMPLE 
SS_USERITEM 
SS_WHITEFRAME 
SS_WHITERECT 


Window Styles 


WS_BORDER 
WS_CAPTION 


WS. CHILD 
WS_CHILDWINDOW 
WS_CLIPCHILDREN 


WS_CLIPSIBLINGS 
WS_DISABLED 
WS_DLGFRAME 
WS_GROUP 


i 


A static control with a black frame outline. 


A static control with the entire center filled with the color used to draw the window frame. 
This is black with the default Windows color scheme. 


A static text contro! with the text centered. 


A static control with the frame color equal to the Windows desktop background. This i is 
gray with the default Windows color scheme. 


A static control with the entire center filled with the color used to draw the Windows 
desktop background. This is gray with the default Windows color scheme. 


A static control containing an icon. The text name specifies the name of the icon to use. 
A static text control with the text left-aligned. 

A Static text control. Text is flush left and truncated to the size of the control. 

A static control when it is desirable to display ampersands (&) in the text of the control. 
A static text control with the text string right-aligned. 

A static text control. 

Auser-defined static control. 

Astatic text control with a frame matching the Wifidows background color (default is white). 


Astatic control with the entire center filled with the color used to draw the parent windows 
oackground. This is white with the default Windows color scheme. * “ 


mx 
Specifies a border on a window . 


Specifies a caption (title) on a window. This cannot be used with the WS_DLGFRAME 
style. 


Creates a child window. This cannot be used with the WS_| POPUP style. 


| Same as WS_CHILD. 


Used when creating the parent window. Specifies that child windows will not extend past 
the boundary of the parent. 


Use with WS_CHILD style. Keeps child windows from overlapping in painting operations. 
Creates a window that is initially disabled (cannot receive the input focus). 
A window with a double border. _ 


This style marks a control that the user can reach by using the direction (arrow) keys. Used 
in dialog boxes. 
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WS | HSCROLL 
~ WS_ICONIC 

WS_MAXIMIZE 
WS_MAXIMIZEBOX 
WS_MINIMIZE 
WS_MINIMIZEBOX 
WS_OVERLAPPED 
WS_OVERLAPPEDWINDOW 


WS_POPUP 
WS_POPUPWINDOW 
WS_SYSMENU 


WS_TABSTOP 
WS_THICKFRAME 
WS_VISIBLE ~ 
WS_VSCROLL 


Table 2-4. Window Styles. 


A window with a horizontal scroll bar. 

A window that is initially iconic. Use with the WS_OVERLAPPED style. 
A window that is initially maximized. | 

A window with a maximize box in the upper right corner. 

Same as WS_ICONIC. 

A window with a minimize box in the upper right comer. 

A window with a caption and a border. 


Combines the WS_OVERLAPPED, WS_CAPTION, WS_SYSMENU, and WS_THICK- 
FRAME styles. This is a standard parent window. 


_A popup window. Cannot be used with the WS_CHILD style. The window can be dis- 
played outside of the parent's boundaries. 


Combines the WS_POPUP, WS_BORDER, and WS_SYSMENU styles. This is a standard 
popup window. 

A window with a system menu. This is the square at the upper left corner of the window. 
Clicking the system menu reveals menu items for “Restore,” “Move,” etc. 


-Used in dialog boxes to specify at which control the tab key stops. 

A window with a thick frame. The frame is used to size the window. 

A window that is initially visible. Used with overlapped and popup windows. 
A window with a vertical scroil bar. 


CREATEWINDOWEX mWin2.0 Win30 Wind 
Purpose Creates new windows with an extended style. 
Syntax HWND CreateWindowEx(DWORD dwEaStyle,LPSTR lpClassName, LPSTR lpWindowName, 


DWORD dwStyle, int X, int Y, int nWidth, int nHeight, HWND hWndParent, HMENU hMenu, 
. HANDLE hinstance, LPSTR lpParam); 
Description The CreateWindowEx() function is used to create child windows with a double border style and/ 
or with WM_PARENTNOTIFY messages disabled. Otherwise, it is identical to CreateWindow(). 
This is an addition to the 3.0 version of Windows. 


Returns HWND, 2 handle to the window created. 

See Also ~ RegisterClass(), ShowWindow(), DestroyWindow(), CreateWindow() 

Parameters ; 
dwkxStyle DWORD: Specifies the extended style to use in creating the window. The only three styles cur- 

rently defined are: 
e Style ce Meaning - Ce eee ne TRAE A? 
WS_EX. DLGMODALFRAME A window with a ails border You can use the WS_CAPTION ahi in the ore naraeer to 
add a title. 


WS_EX_NOPARENTNOTIFY — Prevents WM_PARENTNOTIFY messages from being sent to the parent window when a child 
with this style is created. . 

WS_EX_TOPMOST (Win 3.1) | Windows created with this style remain above all other non-topmost windows, even when deac- 
tivated. The SetWindowPos( function can be used to change this status. 


Table 2-5. Extended Window Styles. 


XN 


24 


| lpClassName 


lpWindowName 


dwStyle 


Y 
nWidth 
nHeight 


hWndParent 


hMenu 


hinstance 


lpParam 


Related Messages. 


Example 


WNDCLASS 


wndclass 
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LPSTR: Pointer to a null-terminated string which contains the name of the window class. Classes - 
can be created using RegisterClass(). 


LPSTR: Points to a null-terminated character string that contains the wid s name. For BUT- 
TON styles, this string becomes the button’s text. For EDIT and STATIC styles, the string is shown 
in the center of the control. 


DWORD: Determines the style of window. The styles can be combined by using the C language 
binary OR operator (I). For example: WS_CHILD | WS_HSCROLL. Styles can be any of those 
listed in Table 2-4 of CreateWindow(). 


int: The horizontal position of the upper left hand corner or the child window or control. You can 
use CW_USEDEFAULT to let Windows decide where to put a program’s window. 
The X and Y positions, as well as the nWdith and nHeight values, are given in device units 


- (pixels). 


int: The vertical position of the upper left corner or the child window or control. You can use 
CW_USEDEFAULT to let Windows decide where to put a program’s window. 


int: The horizontal size of the window or control. You can use CW_USEDEFAULT to let Windows 
decide what size to make a program’s window. 


int: The horizontal size of the window or control. You can use CW_USEDEFAULT to let Windows 
decide what size to make a program's window. 


HWND: A handle to the window’s parent. NULL if there is no parent window. 


HMENU: A handle to the window’s menu. NULL if the class menu is to be used. Use the window 
styles to add or eliminate a menu line from child windows. 


HANDLE: The instance handle for the program module creating the windows. 


LPSTR: A long pointer to a data structure passed to the window. Normally set to NULL, meaning 
that no data is passed via CreateWindow(). 


WM_PARENTNOTIFY, WM_NCREATE 


The following code fragment shows the creation of a window with an extended style as the main 
program window. 


wndclass ; 


~style — = CS_HREDRAw | CS_VREDRAW | CS_PARENTDC ; 


wndclass.lLpfnWndProc = WndProc ; 


wndclass 
wndclass.cbWndExtra 


-cbClsExtra 


wndclass.hInstance = ghInstance' ; 


wndclass. 
wndclass 
wndclass. 
wndclass. 
wndclass. 


hicon NULL ; 

-hCursor = LoadCursor (NULL, IDC_ARROW) ; 
hbrBackground = GetStockObject (WHITE_BRUSH) ; 
lpszMenuName = NULL , 

LpszClassName = "SecondClass" 


/* register the window class */ 


ifCRegisterClass (&wndclass)) 


{ 


hListBox = CreateWindow Ex (WS_EX_DLGMODALFRAME 
“SecondClass", “Child Window", 
WS_CHILD | WS_VISIRLE | WS_CAPTION, 
10, 50, 200, 150, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hListBox, SW_SHOW) ; 
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REGISTERCLASS eWin2.0 eWin3.0 eWin3l 


Purpose 
Syntax : 
Description 


Uses 


Returns 
See Also 


Parameters 
lpWndClass 


style 


Style 


Creates new Windows classes. 
ROOL RegisterClass(LPWNDCLASS lp WndClass); 


RegisterClass() creates a new Windows class that can be used to create any number of new win- 
dows and child controls. 


Used in the WinMain() function to create the ae class for the parent window. Can be used i in. 
the body of the program to create other Windows classes. 


Non-zero (TRUE) if the new class was registered. Zero (FALSE) if the function failed. 


CreateWindow(), CreateWindowEx(), UnregisterClass(), GetClassinfoQ), GortlassLongy), Get- 
ClassName(), GetClassWord(), SetClassLong(), SetClassWord() 


LPWNDCLASS: A long pointer to a WNDCLASS dia tac: This is defined in WINDOWS.H as: 
typedef struct tagWNDCLASS 
{ 


WORD style; 
LONG CFAR PASCAL *lpfnWndProc)(); 
int cbClsExtra; 
int cbWndExtra; 
HANDLE hInstance; 
HICON hiIcon; 
HCURSOR hCursor; 
HBRUSH hbrBackground; 
LPSTR LpszMenuName; - 
LPSTR . LpszClassName; 
+ WNDCLASS; 
typedef WNDCLASS . *PWNDCLASS; 


. typedef WNDCLASS NEAR *NPWNDCLASS; 


typedef WNDCLASS FAR ~~ *LPWNDCLASS; 

The elements of the WNDCLASS structure are as follows: 
WORD: The style parameter can be any of those listed in Table 2-6, combined as desired using the 
C language binary OR operator (1). 


Meaning | 


CS_BYTEALIGNCLIENT Aligns a window's client area on the byte boundaries horizontally. This makes a small savings in 


memory consumed by Windows. 


CS_BYTEALIGNWINDOW Aligns a window on the byte boundaries horizontally. 


~ CS_CLASSDC 


CS_DBLCLKS 


CS_GLOBALCLASS 


CS_HREDRAW 


CS_NOCLOSE 
CS_OWNDC 


CS_PARENTDC 


CS_SAVEBITS 


CS_VREDRAW 


Gives the window class its own device context. ey window created from this class will share 
: the DC. 


Mouse double-click messages are'sent to the window. 

Makes an application global class. Available to all applications while the program that created the 
class is running. 

Redraws the window if the horizontal size changes. 

Stops the close option on the system menu. 


Gives each window instance its own device context. Note that each device context reulee 800. 
bytes of memory. 


The window class uses the parent window's device context. 


Instructs window to save the bitmap of parts of the window that ne be obscurred by overlapping 
windows. 


Redraws the window when the vertical size changes. 


-Table 2-6. RegisterClass() Window Styles 
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lpfnWndProc 


cbClsExtra 


cbWndExtra 


hiInstance 
hIcon 


hCursor 


hbrBackground 


lpszMenuName 
lpszClassName 


2. CREATING WINDOWS _V 


(FAR PASCAL *IpfnWndProc)(): Pointer to the window function. This is usually called 
“WndProc” for the default window function, or another name for a separate message processing 
function that you create for a class of windows. These functions should be referenced in the 

EXPORTS section of the program’s .DEF definition file. . 


int: Sets the number of bytes to include at the end of the window class structure. These extra 
bytes can be used to store information with the class. See the SetClassLong() function descrip- 
tion. 


int: Sets the number of bytes to include after each window instance. This allows data to be stored 
with each window created. See the SetWindowWord() function description. Set this value to 
DLGWINDOWEXTRA if you are using the CLASS directive in your resource (.RC) script file to 
register a dialog box. 

HANDLE: The instance handle of the module (application program) registering the class. 
HICON: Handle for the class icon. If set to NULL, the program must draw the icon if the window 
is minimized. Set to NULL for window classes that are never minimized. 


HCURSOR: Handle to the class cursor. Usually set to the default arrow cursor, as shown in the 
following example. May be set to NULL, if the application explicitly sets the cursor shape when 
processing WM_MOUSEMOVE messages. This is typical of an application that uses one or more 
custom cursor shapes. 


HBRUSH: Handle to the brush used to paint the background. Besides any of the stock brushes 
(see GetStockObject()), the brush can also be set to any of the system colors: 
COLOR_ACTIVEBORDER 

COLOR_ACTIVE CAPTION 

COLOR_APPWORKSPACE ' 

COLOR_BACKGROUND 

COLOR_BTNFACE 

COLOR_BTNSHADOW 

COLOR_BINTEXT 

COLOR_CAPTIONTEXT 

COLOR_GRAYTEXT 

COLOR_HIGHLIGHT 

COLOR_HIGHLIGHTEXT 

COLOR_INACTIVEBORDER 

COLOR_INACTIVECAPTION 

COLOR_MENU 

COLOR_MENUTEXT 

COLOR_SCROLLBAR 


‘COLOR. WINDOW 


COLOR_WINDOWFRAME 
COLOR_WINDOWTEXT 


Add | to these values in the class definition. Although unusual, you can set hbrBackground 
to NULL. This requires that the application Paint the background when a WM_ERASEBKGND 
message is received. ‘ 


LPSTR: Points to the class menu name string. If NULL, the class of windows has no default menu. 


LPSTR: Points to the class menu name string. This is the name that will be used i in the Create- 
Window() function’s [pClassName parametey,vhen creating windows based on the class. 
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Example 


WNDCLASS wndclass ; 


wndclass.style 
wndclass.lpfnWndProc 
wndclass.cbClsExtra 
wndclass.cbWndExtra 
wndclass.hInstance 
wndclass.hIcon 
wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.lpszClassName 


funn bod ow tou a 


CS_HREDRAW | CS_VREDRAW ; 
WndProc ; 


0; 

hInstance ; : 

LoadiIcon ChInstance, gszAppName) ; 
LoadCursor (NULL, IDC_ARROW) ; 
GetStockObject (WHITE_BRUSH) ; 
"generic" ; 

"generic" ; 


/* register the window class */ 
RegisterClass (&wndclass) ; 
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The Windows programming environment provides a wide range of support functions for manipulating windows and 
the data that controls the window's appearance and function. Essentially every aspect of a window’s behavior can be 
determined and changed as the program operates. This frees you from having to keep track of where windows are or 
what they are doing. 


Direct Changes to Window Attributes 


The simplest support functions act directly on a window's behavior or appearance. For example, GetWindowText() 
retrieves the window’s title, while SetWindowText() changes the title to a new string constant. 

You can check the status of a given window with the IsChild(), IsIconic(), IsWindow(Q), and IsWindowVisible() 
functions. Of these, the IsIconic() is the most frequently used. It is commonly put into the WinProc() function to 
change how the client area is paintéd for windows that do not use a class icon (the icon listed in the RegisterClass() 
call in WinMain()). You can paint directly on the little bit of window shown when the program’s window is iconized 
with the normal painting and text functions. Use IsIconic() to find out if ist the icon is showing or if the full window 
is visible. 

MoveWindow() can move and change the size of a window. This is handy if your program uses several child or 
popup windows. You can use the SetFocus() function to change which window or control gets the keyboard input. The” 
window receiving keyboard input is said to have the “input focus.” GetFocus() will tell you which window has the input 
- focus. The SetActiveWindow() and GetActiveWindow() functions are similar. The active window is the parent window 
that has the highlighted title bar and currently receives messages from Windows for mouse movements, etc. Active 
status applies only to parent windows. Focus can apply to a parent or child window. 


Changing the Class Data 


AS we saw in Chapter 2, creating a window is a two-step process. You first need to create a window class using 

‘RegisterClass(). Then you create one or more windows based on this class using the CreateWindow() function. As the 
program operates, you may want to change some of the data in either the class structure or in the parameters passed 
to the CreateWindow() function. The several functions reading or changing a class data structure work on the differ- 
ent data types in the window class structure, WNDCLASS, as shown in Listing 3-1. 


Listing 3-1. WNDCLASS Definition in WINDOWS. H 
typedef struct tagWNDCLASS 
{ 


WORD style; 

LONG CFAR PASCAL *lLpfnWndProc)(); 
int cbClsExtra; 

int cbWndExtra; 

HANOLE hInstance; 

HICON . hicon; 

HCURSOR hCursor; 

HBRUSH hbrBackground; 

LPSTR LpszMenuName; 

LPSTR LpszClassName; 


} WNDCLASS; 


GetClassWord() retrieves WORD long values, while GetClassLong() retrieves LONG values. To use these , you will 
have to mentally convert between the Windows naming conventions defined in WINDOWS.H. For example, 
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WORD == unsigned int, HANDLE, HICON, HCURSOR, HBRUSH = 2 Bytes 


Changing a class value with SetClassWord() or SetClassLong() affects every window that was created from that class. 
This is handy for globally changing the cursor shape or using a different color brush for every window's background. 
Changes to an individual window are less drastic. SetWindowWord() and SetWindowLong() affect just one window, 
not every one in the class. These modified windows are a “subclass.” An interesting possibility here is to change the 
window message function referenced by a window to a new function. This is called “window subclassing.” The ex- 
ample shown after the SetWindowLong() function description changes the default processing for a scroll bar to in- 
clude the handling of arrow keys and page-up/page-down keys. These logic items are added to the normal Windows 
processing of scroll bar messages, providing a custom version for that one window control. 


Data Attached to a Window or Class 


‘Windows has a powerful ability to associate data with a window or window class. A typical use would be in an applica- 
tion with several similar child windows. Each child window can store its own data to work on, while making use of a 
single message processing function. For small amounts of data, the data can be made a part of the class definition. The 
cbClsExtra element in the WNDCLASS structure sets the amount of extra data stored with the window class. This is 
common to all windows created from the class. The cb¥ndEztra element in WNDCLASS sets the amount of extra data 
stored with each window. This is the more common use. 

The problem with using extra bytes in the WNDCLASS definition is that the data is not structured. The program: 
must keep track of the meaning and location of each byte: A good way to use this data is to simply store a handle toa 

’ memory block with the window (memory allocation is discussed in Chapter 14). The memory block can then contain 

‘ alarge amount of data, defined by a custom data structure. This technique is used in Chapter 29 for the child windows 
in the MD] (Multiple Document Interface) example. - 

. Amore elaborate way to store data with a window is provided with the “property” functions. Properties amount to 

named data. Each property is given a name and a handle pointing to a memory area allocated to store the data. You 
attach the property to the window with the SetProp() function. A typical call might be 


: SetProp ChWnd, "Prop1"); . 
Any time the window hWnd wants to get the handle to the data, it uses GetProp() something like 
hDataHandle = GetProp (hWnd, “Prop1") : 


The data is then extracted from memory after locking the data (see Chapter 14 on memory functions for details). 
You can also release the property from the window using ReleaseProp(). There is also an EnumProp() function for 
finding all of the properties associated with a window. With well-designed structures for your data, the property 
facility will greatly improve the “object oriented” nature of your windows and reduce the need for global data structures. _ 


Notes: Enumeration Functions 


The most powerful, but most difficult to use of the windows support functions are the enumeration functions. They are 
used ina series of situations where you want to get a list of information, but you do not know how many items there will 
be in the list. For example, asking for a list of child windows attached to a parent: EnumChildWindows(); alist of property 
data attached to a window’s definition: EnumProps(); a list of the program “tasks” 
running on the system EnumTasks(); or just a list. of windows on the screen: 
EnumWindows(). (“Tasks” are application programs running on the system. This ‘totic Text 
does not include dynamic link libraries (DLL's). “Modules” is the term Windows = [fie 2#'E#hs73 
uses for all running programs, including DLLs.) | 
To deal with these problems, the enumeration functions require that youwrite scan are Sesh 
a short function in your program that the Windows enumeration function will call | 


Button 


every time it finds an item that needs to be remembered. You write the enumera- Ste Text 


Edit Me 


tion function to make an ever-expanding list of the items, adding one to the list 
each time the function is called. In general, these items will be of equal length. The Figure 3-1. Child Windows — 
following listings are provided to show an example. In this case, a list of all ofthe Hnumerated 
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names of the child windows for a program are enumerated. When the user clicks the “Do It!” menu item, the names 
are shown on the parent window’s client. area. ‘The result i is shown in Figure 3-1. 

_ Notein the header file that a new data type is created, called ENUMER. This contains a handle pointer to memory 
and a count of the number of items which are stored in the memory location. Also note the declaration for the enu- 
meration function at the bottom, as shown in Listing 3-2. 


& Listing 3-2. WINDENUM.H—Header File for Child Window Enumeration 
/* windenum.h = */ 

/* menu item id values */ 

4define IDM_DOIT 1 
_ define IDM_QUIT 2 


/* definitions */ 
Hdefine TITLEWIDE 20 


typedef struct 
£ 


GLOBALHANDLE hGMem ; 
int nCount ; 
} ENUMER ; 


/* gtobal variables */ 
int ghIinstance ; 
char . gszAppName CJ = “WndEnum" ; 


/* function prototypes */ 
Long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 
BOOL FAR PASCAL WndEnumFunc CHWND, ENUMER FAR *) ; 


The enumeration function must be declared in the EXPORTS section of the program’s .DEF definition file, as Win- 
dows. (See Listing 3-3.) 


Listing 3-3. WINDENUM.DEF 


NAME WINDENUM 

DESCRIPTION ‘windows enumeration example' 

EXETYPE WINDOWS. 

STUB "WINSTUB.EXE' 

CODE PRELOAD MOVEABLE 

DATA PRELOAD MOVEABLE MULTIPLE 

HEAPSIZE 1024 

STACKSIZE 5120 ; : 

EXPORTS , WndProc : 1 
i -WodEnumFunc 


Note in the C language Listing 3-4 that the enumeration function must be registered with Windows using the 
MakeProclnstance() function before it is used. Also note in the enumeration function that each new chunk of data is 
added to the end of the last bit. 


CG Listing 3-4. WINDENUM.C WndProc() Function 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
c 4 

static HWND hButton ; : 

static HWND hStaticText ; ae 

static HWND hEdit ; 

static FARPROC LpfEnumProc ; 

static ENUMER enumer ; 

LPSTR~ LpWindName ; 

HOC : hoc ; 

int iy. . = 

switch (iMessage) _. d /* process windows messages */ 


case WM_CREATE: 


hButton = CreateWindow ("BUTTON", "Button", 
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} 


} 


nae 


WS_ CHILD | WS_VISIBLE | BS_PUSHBUTTON, 

10, 10, 100, 40, hWnd, NOLES ghInstance, NULL) ; 
ShowWindow (hButton, SW_SHOW) ; 

/* create and show static text */ 

hStaticText = CreateWindow C"STATIC", "Static Text", 

WS CHILD | WS_VISIBLE | BS_PUSHBUTTON, 

150, 10, 100, 15, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hStaticText, SW_SHOW) ; 

; /* create and show an edit control */ 

hEdit = CreateWindow ("EDIT", “Edit Me", 

WS_CHILD {| WS_VISIBLE | WS_BORDER, 

150, 40, 100, 25, hind, NULL, ghInstance, NULL) : 
ShowWindow Chedit, SW_ SHOW) ; 


LpfEnumProc = MakeProcInstance (WndEnumFunc, 


ghInstance) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 


case WM_ DESTROY: 


default: 


return (QOL) ; 


if Cenumer.hGMem) /* if not first time tried */ 
GlobalFree Cenumer.hGMem) ; /* free the memory */ 
/* initialize storage area */ 
enumer.hGMem = GlobalAlloc (GMEM_MOVEABLE | GMEM_ZEROINIT, 
1L) ; 
enumer.nCount = 0 ; 


/* let Windows run callback func. */ 


EnumChildWindows ChWnd, lpfEnumProc, 
CDWORD) &enumer) ; 

hDC = GetDC (hWnd) ; /* get ready to output */ 
LpWindName = GlobalLock Cenumer.hGMem) ;/* Lock memory */ 
TextOut ChDC, 10, 100, "EnumChildWindows() found:", 25) ; 
for (i = 0 ; i < enumer.nCount ; i++) /* display window */ 
{ /* titles found */ 
TextOut (hDC,'15, 125 + (15 * i), 

(LPSTR) ClpWindName + (i * TITLEWIDE)), 

Lstrlen (lpWindName + (i * TITLEWIDE))) ; 


} i 

GlobalUnLock Cenumer.hGMem) ; /* unlock memory */ 
ReleasePG ChWnd, hDC) ; 

break ; 


case IDM_QUIT: 

DestroyWindow ChWnd).; 
: break ; Z 
} 
break ; ‘ 
eh stop application */ 
GlobalFree Cenumer.hGMem) ; /* release all memory */ 
PostQuitMessage (0) ; 
break ; 

/* default windows message processing */ 

return DefWindowProc Chiind, iMessage, wParam, LParam) ; 


/* this is the enumeration function, called once for each window */ 


BOOL FAR PASCAL WndEnumFunc CHWND hWindow, ENUMER FAR *enumer) 


{ 


LPSTR 
char 


LpWindName ; 
cBuf CTITLEWIDE + Ww; 


if (!GlobalReAl Loc Cenumer->hGHem, 


CDWORD) TITLEWIDE * Cenumer->nCount + 1), 
GMEM_MOVEABLE)) /* make room for 10 more. */ 


‘peturn (0) ; /* quit if can't make room */ 
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GetWindowText (hWindow, (LPSTR) cBuf, TITLEWIDE) ; 

cBuf CGetWindowTextLength (hWindow)] = oe ; /* add end null */ 

LpWindName = GlobalLock Cenumer->hGMem) ; /* Lock the memory area */ 
Sa /* put next name at end */ 

Lstrepy (lpWindName + CCenumero-nCount? * TITLEWIDE), CLPSTR) cBuf) ; 

GlobalUnlock Cenumer->hGMem) ; /*® unlock the memory area */ 

enumer->nCount++ ; /* keep track of how many */ 

return (1) ; 


/* get title */ 


All enumeration functions use this basic structure, aienoigh the parameters passed to the callback function will 
be different. 


Cautions 

It is fairly easy to create an infinite loop of Windows messages, This ihofabs the program ina hurry. For example, if you 
decide to create a number of child windows in the WM_CREATE portion of your WinProc() function, you will have 
trouble. Each time you create a new window, a WM_CREATE message is sent. Use a static BOOL variable to track if 
this is the first time the WM_CREATE message was issued. Be careful when changing the background color of a 
window class. The change will not show up immediately if you do not force the window to be repainted using | 


UpdateWindow(). 


- Fanction Descriptions 
Table 3-1 summarizes the Windows support functions. The detailed function descriptions are immediately after the 


table. 


AdjustWindowRect 


~, Purpose 


Computes how big the entire window must be to sees a window with a given client area size. 

AdjustWindowRectEx Computes how big the entire window must be to produce a window with a given client area size 
for a window with an extended style. 

AnyPopup Determines if any popup windows are on the screen. 

BeginDeferWindowPos Begins rapid movement of a window on the screen. 

BringWindowToTop Makes a window visible, if it is underneath other overlapping windows. 

ChildWindowFromPoint Determine which child window occupies a given point on the parent window. 

CloseWindow Minimizes a window. 

DeferWindowPos Causes rapid movement of a window on the screen. 

DestroyWindow Removes a window from the system. 

EnableWindow Enables or disables mouse and keyboard input for the specified window. 

EndDeferWindowPos Completes a rapid movement of a window on the screen. The movement occurs when this func- 
tion is called. : 

EnumChildWindows Calls an enumeration function for all of the child windows of a parent. 

EnumProps Retrieves all of the entries in the property list of a window. | 

EnumTaskWindows Lists all of the top-level windows associated with a task. 

EnumWindows Retrieves data on all of the parent windows running on the system. 

FindWindow Retrieves a handle to a window. 

FlashWindow Highlights the window's caption bar. 

- GotActiveWindow Finds which parent or popup window is active. 
GetClassLong Retrieves a long value from a class structure. 
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Table 3.1 continued 


Function 


‘GetClassName 
GetClassWord | 
GetClientRect 
GetCurrentTask 
GetDesktopWindow 
GetFocus 


Retrieves the class name upon which a window is based. 

Retrieves information from a class. 

Retrieves a window’s client area size. 

Retrieves a handle te the currently executing task. . 

Retrieves the handle of thé background window that covers the entire screen. 
Finds which window has the input focus. . 


GetLastActivePopup Finds which popup window was last active. 


GetNextWindow : 
GetNumTasks 
GetParent 

GetProp 
GetSysModalWindow 
GetTopWindow 
GetVersion 
GetWindow 
GetWindowLong 
GetWindowRect 
GetWindowTask 
GetWindowText 
GetWindowTextLength 
GetWindowWord 
GetWinFlags 

IsChild 

Islconic 

IsWindow 
lsWindowEnabled 
IsWindowVisible 
IsZoomed 
.MoveWindow 
RemoveProp 
SetActiveWindow 
SetClassLong 
~SetClassWord 
SetFocus 

SetParent 

SetProp 
SetSysModalWindow 


Finds parent and child windows. 


Finds te number of tasks running in the system. 


Retrieves a handle to a parent window. 


Retrieves a property (data) associated with a window. 
Retrieves a handle to a system modal window. 

Finds the child window on top of any other child windows. 
Retrieves the version number of Windows running on the system. 
Retrieves a window's handle. 

Retrieves a long value from a window’s data. 

Retrieve aon outer dimensions. 

Retrieves: handle to a task. | 

Retrieves a'window's title string. 

Finds the number of characters in a window’s title string. 
Retrieves a two byte value from a window’s data. 

Determines what computer CPU and memory model are in operation. 
Determines if a window is the child of a given parent window. 
Checks if a window is minimized. 

Checks if a window handle still points to a valid window. | 
Checks if a window is enabled for keyboard input. 

Checks if a window has been made visible, 

Checks if a window is maximized. 

Moves or resizes a window. 

Removes a proverty (data) which was associated with a window. 
Makes a window visible. 

Changes one of the LONG values in a window class. 

Changes a WORD sized value in a window class. 

Gives a window the input focus. 

Changes the parent window of a child window. 

Attaches named data to a window. 

Makes a window s)stem-modal. 
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SetWindowLong | Changes a LONG value associated with a window. 
SetWindowPos Simultaneously changes the size, position, and ordering of windows. 
SetWindowText "Changes thé title of a window. 
SetWindowWord Changes a WORD value associated with a window's class structure. 
ShowOwnedPopups Shows or hides all popup wincows associated with the parent window. 
ShowWindow Displays, hides, or changes the size of a window. 
SystemParametersinfo Determines and/or changes system wide parameters. - 
UnreyisterClass — ~ Frees the memory holding an unneeded class description. . 
WindowFromPoint Finds which window (if any) is at a given poim on the screen. 
Table 3-1. Windows Support Functions Summary. ye Pes 
ApsJUSTWINDOWRECT mWin2.0 mWin30 mWin3.1 
Purpose Computes how big the entire window must be to produce a window with a given client area size. 
Syntax void AdjustWindowRect (LPRECT /pRect, LONG dwStyle, BOOL bMenz); 
Description Changes the contents of the IpRect from those of the client rectangle to that of the bounding 
rectangle. The bounding rectangle encloses the caption, menu bar, and window frame. 
Uses Generally used with CreateWindow() to make a new window of a given size. 
Returns - No return value (void). 
See Also AdjustWindowRectEx(), CreateWindow(), MoveWindow(). 
Parameters 
lpRect LPRECT: A pointer to a RECT rectangle structure. 
dwStyle DWORD: The window style. This includes any of the window style values from the 
CreateWindow() function (Chapter 2). 
bMenu BOOL: Specifies if the window size calculated should ‘ich space for a menu. Set to TRUE to 
on include the menu space, FALSE to omit. 
Example In this example the adjusted rectangle is used in the CreateWindow() function. The final window 


in this case is converted. from the client size of 50, 50, 150, 150 to the total window dimensions 49, 
30, 151, 151. 


long FAR PASCAL WndProc CHKWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC . 
static WNDCLASS 
7 static HWND 
‘ RECT 


switch (iMessage) 
{ 


hoc >, . /* device context handle */ 
wndclass ; /* the window class */ 
hListBox ; /* the window handle */ 
rWindRect ; : 


/* process windows messages */ 


case WM_CREATE: /* build the child window when program starts */ 
rWindRect. top = 50; /* client area size desired */ 
rWindRect.left = 50 ; 
rWindRect.bottom = 150 ; 
rWindRect.right = 150 ; 


AdjustWindowRect(&rWindRect, /* rectangle to convert */ 
WS_CHILD {| WS_VISIBLE | WS_BORDER | WS_CAPTION, 
FALSE) ; / /* no menu */ 


‘CS_HREDRAW {| CS_VREDRAW | CS_PARENTDC ; 
ChitdProc ; 


wndclass.style 
wnidclass.lpfnWndProc 
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-wndclass.cbClsExtra 0; 
wndclass.cbWndExtra 0; 
wndclass.hInstance ghinstance i. 
wndclass.hIcon NULL ; 


wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
-wndclass.lpszClassName 


LoadCursor (NULL, IDC_CROSS) ; 
GetStockObject (LTGRAY_ BRUSH) ; 
NULL ; 
“SecondClass” ; 

/* register the window class */ 
ifCRegisterClass (&wndclass)) 
{ 


1 


hListBox = CreateWindow ("SecondClass", "Child Window", 
WS_CHILD | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
rWindRect. left, rWindRect.top, 
rWindRect.right, rWindRect. eOetOny 
hWnd, NULL, ghinstance,_ NULL) ; 

ShowWindow ChListBox, SW_SHOW) ; 


break ; 
[Other program lines] 
ApsusTWINDOWRECTEX 7 wWin2.0 mWin3.0 mWin3.1 
Purpose — Computes how big the entire window must be to produce a window with a given client area size 
. - for a window with an extended style. 
Syntax void AdjustWindowRectEx(LPRECT /pRect, LONG dwStyle, BOOL bMenu, DWORD dwExstyle); 
Description Changes the contents of the /pRect from those of the client rectangle to those of the bounding 
: rectangle. The bounding rectangle encloses the caption, menu bar, and window frame. 
Uses Generally used with CreateWindowEx() to make a new window of a given size. . 
Returns No returned value (void). 
See Also ' AdjustWindowRectEx(), CreateWindowEx(), MoveWindow(). 
Parameters ns ae 
- bpRect -LPRECT: A pointer to a rectangle structure. 
dwStyle DWORD: The window style. This includes any of the window style values from the 
CreateWindow() function. 
bMenu BOOL: Specifies if the window size calculated, should include space for a menu. Set to TRUE to 
include menu space, FALSE to omit. 
dwkxStyle DWORD: The extended style values used in the CreateWindowEx() function. 
Example Note that the adjusted rectangle is used in the CreateWindowEx() function. The final window in 


this case is converted from the client size of 50, 50, 100, 100 to the total window dimensions 45, 
29, 155, 155. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ine : : 


HDC hDC ; /* device context handle */ 

static WNDCLASS wndclass ; /* the window class */ 

static HWND ' hTextBox ; /* the window handle */ 

RECT S a rWindRect ; 

switch CiMessage) ! , /* process windows messages */ 7 
{ 


case WM_CREATE: /* build the child window when program starts */ 
rWindRect.top = 50 ; /* client area size desired */ 
rWindRect.left = 50 ; : 
rWindRect.bottom = 150 ; 
rWindRect.right = 150 ; 


AdjustWindowRectEx(&rWindRect, 
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WS_CHILD | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
FALSE, WS_EX_DLGMODALFRAME) ; 


CS_HREDRAW | CS_VREDRAW | CS_PARENTDC ; 
ChildProc ; 


wndclass.style 
wndclass.lpfnWndProc 


wndclass.cbClsExtra 0; 
wndclass.cbWndExtra 0; 
wndclass.hInstance ghInstance ; 
wndclass.hIcon NULL ; 


wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.lpszClassName 


LoadCursor (NULL, IDC_CROSS) ; 
GetStockObject (LTGRAY_BRUSH) ; 
NULL ; 
“SecondClass" ;, 
/* register the window class */ 


uHn nb bonne 


if(RegisterClass (&wndclass)) 
{ 


hTextBox = CreateWindowEx (WS_EX_DLGMODALFRAME, 
“SecondClass", "Child Window", 
WS_CHILD | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
rWindRect.left, rWindRect.top, 
rWindRect.right, rWindRect.bottom, 
hWnd, NULL, ghInstance, NULL) ; 

ShowWindow (hTextBox, SW_SHOW) ; 


} 
break ; 

[Other program lines / 

AnyPoPuP | | wm Wind.0 sm Win3.0 Win 3.1 

Purpose Determines if any popup windows are on the screen. 

Syntax BOOL AnyPopup(void); 

Uses Popup windows can overlap any portion of the parent’s window. This function will tell you if any 
popups exist. 

Returns ~ BOOL, TRUE, or FALSE. 

Parameters . None (void). 

Example This fragment shows a WndProc() function checking if there is a popup window before starting to 
refresh the screen. It may be desirable to close the popup window before painting to eliminate 


hidden areas. 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hoc ; 
static BOOL bPopupExist ; 


switch (iMessage) /* process windows messages */ 
{ 
case WM_PAINT: 


if (AnyPopup()) Be os 
bPopupExist = TRUE ; : 


else : 
bPopupExist = FALSE ; 
break ; . 

[Other program lines] 
BeGINDEFERWINDOWPos | OWin2.0 mw Win30 aWin3.l 
Purpose Begins rapid movement of a window on the screen. . 
Syntax -- HANDLE BeginDeferWindowPos(int nNumWindows); 
Description This function is the first step in the sequence of functions BeginDeferWindowPos(), Defer- 

WindowPos(), and EndDeferWindowPos(), used to move one or more windows in a single screen 

refresh cycle. 
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Uses "Animation of windows byrepeatedly . 
moving them, or just fast movement 
of a single window to a new location. 


Returns A handle to the multiple-window 
data structure used by DeferWin- 

dowPos(). 
See Also BeginDeferWindowPos(), | 

DeferWindowPos(),. 

EndDeferWindowPos(), _ 

~ MoveWindow(), SetWindowPos() 

Parameters : Figure 3-2. BeginDeferWindowPos() Example. 


nNumWindows int: Sets the number of windows 
that will be affected by the window movement. This initializes the data structure. Getting the. 
correct value is not critical, as the data structure will be expanded (with some loss of speed) if 
DeferWindowPos() requires more windows to be updated. 


Example This example, illustration Figure 3-2, creates two button child windows at the bottom of the 
client area. When the user clicks the “Do It!” menu item, both buttons are relocated to the top of 
the client area. a 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HWND hTestBox1, hTestBox2 ; 

“static HANDLE hDeferData ; /* handle for DeferWindowPos() */ 
switch (iMessage) I* process windows messages */ 

{ , ; 


case WH_CREATE: /* create a s button when program starts */ 
“hTestBox1 = CreateWindow C“BUTTON", “Moving Button 1", 
WS_CHILD | WS_VISIBLE , 
200, 200, 150, 50, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChTestBox1, SW_SHOW) ; - 
hTestBox2 = CreateWindow (“BUTTON", “Moving Button 2", 
WS_CHILD | WS_VISIBLE , = 
0, 200, 150, 50, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChTestBox2, SW_ SHOW) ; 
hDeferData = BeginbeferwWindowPos. (2) >; 
hDeferData = DeferWindowPos (hbeteroata, hTestBoxt, 
hTestBox2, 10, 10, 200, 50, SWP_NOSIZE) ; 
hDeferData = DeferWindowPos (hDeferData, hTestBox2, 
NULL, 180, 10, 200, 50, SWP_NOSIZE) ; 


break ; is 
case WM_COMMAND: ae /* process menu items */ 

switch (wParam) 

{ 

‘case IDM_DOIT: /* move the button */ 
EndDeferWindowPos (hDeferData) ; ‘/* move windows */ 
InvalidateRect (hWnd, NULL, TRUE) >; © /* force paint */ 
break ; 


case IDM_QUIT: 
DestroyWindow ChWnd) ; 


¢ break ; 
> 
break ; ; 
' case WH_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 


r : return OefWindowProc (hWnd, iMessage, wParam, lParam) ; 
return (OL) ; _ 
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BrincWinpowToTopr mWin2.0 8Win3.0 ewWind! 


Purpose Makes a window visible and activates it (for a popup or top-level window) if the window is under- 
. neath other overlapping windows. 

Syntax void BringWindowToTop(HWND hWnd); 

Description The window chosen is superimposed over any other ieeilaawing windows on the screen. The 
window is activated if it is a popup or top-level window. 

Uses Most often used with popup windows. 

Returns — No return value (void). ; : 

See Also SetFocus(), IsWindowVisible(), SetActiveWindow(), EnableWindow() 

Parameters 

hWnd HWND: Handle of the window to bring tothe top. _ 

Example This example swaps the superposition of the two button controls on the screen when the “Do It!” 
menu item is clicked. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 

{ cae 
static HWND hTestBox1, hTestBox2 ; ./* the window handles */ 
switch CiMess ae): /* pencess windows messages */ 
{ F 


case WM_CREATE: /* build the child windows when program starts a) 

hTestBoxi = CreateWindow ("BUTTON", "BUTTON 1", 

WS_ CHILD | WS_VISIBLE , 

10, 50, .110, 100, hWnd, NULL, ghIinstance, NULL) ; 
ShowWindow ChTestBox1, SW_SHOW) ; 
hTestBox2 = CreateWindow ("BUTTON", “BUTTON 2", 

WS_CHILD | WS_VISIBLE , 

30, 70, 130, 130, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (nTestBox2, SW_SHOW) ; 


break ; 
case WH_| CONHAND: /* process menu items */ 
switch (wParam) 
{ : 
case IDM_DOIT: /* User hit the “Do it” menu item */ 
BringWindowToTop (hTestBox2) ; /* no 1 to top */ 
StowWindow ChTestBoxt, SWLHIDE) ; /* refresh screen */ — 
Showa ndou ChTestBox1, SW_ SHOWNORMAL) ; 
break ; 
[Other program lines]. 
CumpWinnowF 2oMPoInt | mg Win2.0 mWin3.0 mWin3.l 
Purpose Determines which child window occupies a given point on the parent window. 
Syntax HWND ChildWindowFromPoint(HWND hWndParent, POINT Point); 
Description Returnsa handle to the child window at a given point. 
Uses Handy if the application uses several child windows, which may be obscuring data on the screen. 


Typically used with the mouse cursor to determine which child the cursor is over, independent of 
the mouse buttons being pressed. 


Returns A handle to the child window, NULL if no child window is at the ae 


See Also WindowFromPoint(), ScreenToClient() Se 
Parameters \ 
hWndParent HWND: The parent window’s handle. 

Point POINT: The client area coordinates to check. . 


Related Messages WM_MOUSEMOVE | 
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Cautions _ This function will not work properly over pushbutton controls. 


Example This example, as shown in Figure 3-8, displays the name of the Dolt! Quit 
window the mouse is pointing to as the cursor is moved over [Child Window = Static Text 2 
the client area. Two static text windows are placed on the cli- 


P Static Text 1 
ent area. The figure shows the mouse cursor over the lower ees 
Static Tqxt 2 


one. The handle of the child window is retrieved using { 
ChildWindowFromPoint(). The name of the window (the a Figure 3-3. ChildWindow- 
tion string) is determined with GetWindowText(). FromPoint()Example. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ® 


HWND hStaticl, hStatic2, hWndTest ; 

HDC Abe ; 

POINT pMouse ; 

char cBuf [128], cBuf2 £256] ; 

switch (iMessage) _ /* process windows messages */ 
{ : 


case WM_CREATE: 
hStaticl = CreateWindow ("STATIC", "Static Text 1", 
WS_CHILD | WS_VISIBLE | BS_ PUSHBUTTON, 
. 10, 40, 100, 20, hWnd, 100, ghingtance, NULL) - 
ShowWindow (hStaticl, SW_ SHOW) : 
hStatic2 = CreateWindow C"STATIC", “Static Text 2", 
WS_CHILD | WS_VISIBLE | BS_’PUSHBUTTON, 
: 10, 60,°100, 20, hWnd, 101, ghinstance, NULL); 
ShowWindow ChStatic2, SW_SHOW) ; 
break ; 
case WM_MOUSEMOVE: 
pMouse = MAKEPOINT (lParam) ; 
hDC = GetDC ChWnd) ; 
hWndTest = ChildWindowFromPoint ChWnd, pMouse) ; 
‘if ChWndTest) 
GetWindowText ChWndTest, cBuf, 127) ; 
else 
istrcepy (cBuf, "<none>") ; 
TextOut ChDC, 0, 0, cBuf2, wsprintf (cBuf2, 
: "Child Window = = Zs", (LPSTR) cBuf)) ; 
Vigil ReleaseDC ChWnd, hDC) ; 
. break ; 
case WM COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; : oe 
case WM_ DESTROY: /* stop application */ ‘s 
PostQuitMessage (0); ‘. 


break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
4 : 
return (OL) ; 
} 
-CLOsEWINDOW - stg . fWin20 8Win30 mWin3.1 
Purpose / i ‘Minimizes a window. 
Syntax - void CloseWindow(HWND hWnd); 
Description If the window’s class structure contains an icon, the minimized window will display the icon 


’ image. Otherwise, the. minimized window will be a blank client area, which will receive 
WM_PAINT messages and can be painted on using normal painting functions. 
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Uses Used in applications with several child windows. The closed windows remain on the bottom of the 
parent’s client area. Double-clicking the minimized windows automatically restores them to their 
previous size. 

Returns No return value (void). 

See Also IsIconic(), IsWindowVisible(), IsZoomed(), OpenIcon() 

Parameters : 

hWnd HWND: The window's handle. 

Related Messages WM_SIZE, WM_PAINT 

' Example In this example, clicking the “Do It!” menu item causes the button child window to be minimized 


to the bottom of the parent window's client area. Double-clicking the minimized button restores it. 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
Peas 


static HWND hButton ; 


switch (iMessage) /* process windows messages */ 
{ : 
case WM_CREATE: 
hButton = CreateWindow ("“BUTTON", "Button", 
WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON, 
10, 19, 100, 40, hWnd, NULL, ghinstence, NULL) ; 
showlindow ‘hButton, SW_! SHOW) ; 
break ; a 
case WM _ COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: 


ClLoseWindow ChButton) ; /* minimize button */ 
break ; 
[Other program lines] 
DeFERWINDOWPos_- -. OWin2.0  =Win30 mWin3l 
Purpose Produces rapid movement of a window on the screen. 
Syntax HANDLE DeferWindowPos(HANDLE hWndPosInfo, AWND hWnd, HWND hWndInsertAfter, int 
x, int y, int cx, int cy, WORD wFlags); 
Description This is the second function in the series BeginDeferWindowPos(), DeferWindowPos(), EndDefer- 


WindowPos() that allows rapid movement of a window on the screen, all within one screen 

_ refresh cycle. DeferWindowPos() sets values in an internal data structure created by BeginDefer- 
WindowPos(). These values are then used by EndDeferWindowPos() to do the actual movement 
of the window on the screen. . 


Uses Animation of windows by repeatedly moving them, or just fast movement of a single window to a 
, new location. 

Returns A handle to the data structure used by DeferWindowPos(). 

See Also BeginDeferWindowPos(), EndDeferWindowPos() 

Parameters a 

hWindPosInfo HANDLE: The handle to the internal data structure returned by BeginDeferWindowPos(). 

«hWnd HWND: The window handle of the window to be moved. 
hWndInsertAfter HWND: The window handle of the previous window to be moved. NULL if hWnd is the first one. 
rae int; The X-coordinate of the upper left corner of the window after it has been moved in client 
coordinates (pixels from the upper left corner of the client area). 
y int: The Y-coordinate of the upper left corner of the window after it has been moved in client 


coordinates. 
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_ int: The new width of the window in pixels. 


Cx 
cy int: The new height of the window in pixels. 
wFlags WORD: One of the values in Table 3-2. 


WP. DRAWERAME Bras the frame specified in the window's class joao when redrawn. 
SWP_HIDEWINDOW Hides the window when redrawn. 
SWP_NOACTIVATE ‘Does not activate the window. 
SWP_NOMOVE Does not move the window, but the size can be changed with the cx,cy parameters. 
SWP_NOREDRAW Does not redraw the window at the new size/ocation. 

’ SWP_NOSIZE . Does not resize the window, bitt the position can be changed with the x,y parameters. 
SWP_NOZORDER . | Retains the current ordering in the reposition list. If hWndinsertAfter is NULL, hWnd is placed at 

the top of the list. If hWndinsertAfter is 1, hWnd is placed at the bottom of the list. 

SWP_SHOWWINDOW Displays the window when redrawn. 


Table 3-2. DeferWindowPos() Flags. 


Example See the example under the BeginDeferWindowPos() function description. ~ 


DestroyWinpow wWin2.0 wWin30 mWin3! 
Purpose © Removes a window from the system. , 
Syntax BOOL DestroyWindow(HWND hWnd); + 


Description The window referenced by hWnd is deleted. Any child windows of hWnd are deleted first, fol- 
lowed by the parent. The window's class is not affected, unless this is the last window on the 


-system using the class. 
Uses -: Removing popup and child windows from the screen when not needed. Also used to stop an appli- 
cation by destroying the parent window. 
Returns BOOL. TRUE if the window was destroyed, FALSE if the function failed (normally meaning that 
. . hWnd did not exist). 4 
See Also Maregar Clas) Creation) 
Parameters — 
hWnd HWND: Handle of the window to be destroyed. 
Related Messages WM_DESTROY, WM_NCDESTROY, WM_! OTHERWINDOWDESTROYED 
Example In this example, clicking the “Do It!” menu item causes the popup window to be destroyed and its 
class to be unregistered. 


The ChildProc() function needs to. be listed in the EXPORTS section of the program's .DEF 
file, and a function prototype needs to be added to the header file to use this example code. ~ 


tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ‘ 


static WNDCLASS wndclass ; /* the window class */ 
static HWND “hPopup ; 
switch (iMessage) /* process windows messages a/ 


case WH_CREATE: /* build the child window when program starts */ — 
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wndclass.style 


CS_HREDRAW | CS_VREDRAW | CS_PARENTDC; 
wndclass.lpfnwWndProc ; 


ChildProc ; 


wndclass.cbClsExtra 0; 
wndclass.cbWndExtra 0; 
wndclass.hInstance ghInstance ; 
wndclass.hIcon NULL ; 


LoadCursor (NULL, IDC_ARROW) ; 
GetStockObject (LTGRAY_BRUSH) ; 
NULL ; 
“SecondClass” ; 

/* register the window class */ 
if(RegisterClass (&wndclass)) 
{ 


wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lLpszMenuName 
wndclass.lpszClassName 


unr oubtnruwna 


hPopup = CreateWindow ("SecondClass", "Popup Window", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 50, 206, 150, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChPopup, SW SHOW) ; 
} 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT:. /* User hit the "Do it" menu item */ 
DestroyWindow (hPopup) ; 
UnregisterClass ("SecondClass" ghInstance) ; 
break ; 
case IDM_QUIT: /* terminate this application */ 
DestroyWindow (hWnd) ; 
break ; 


_—_— 


} 
break ; 
- case WM_DESTROY: s 
PostQuitMessage (0) ; 
break ; : 
default: /* default windows message processing */ 
return DefWindowProc (hind, iMessage, wParam, lParam) ; 


: return (OL ;° 

3 
. ee 

/* Here is a separate message processing procedure for the child window */ 

long FAR PASCAL ChildProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 

{ 

switch CiMessage) /* process windows messages */ 


case WM_DESTROY: 


b k > : 
default: rer /* default windows message processing */ 
a return DefWindowProc (hind, iMessage, wParam, LParam) ; 
} . 
return (OL) 5 
} 
ENABLEWINDOW  @Win2.0 sm Win30) Wind 
Purpose Enables or disables mouse and keyboard input or the specified window. a 
Syntax — BOOL EnableWindow(HWND hWnd, BOOL bEnabie); 
Uses ; , Handy for controlling where a user is allowed tc input data. For example, an edit control may be 
enabled to input a file name only after a subdirectory has been chosen. A window must be en- 
abled before it can be activated. Windows are automatically enabled when created. 


Returns BOOL. TRUE if successful, FALSE if the function failed. 
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See Also SetFocus(), GetFocus(), SetActiveWindow() 

Parameters <3 . . 

hWnd HWND: The handle of the window to affect. 

bEnable . BOOL: TRUE to enable, FALSE to disable. 

Example ' This example shows the creation of an edit control. The control is initially disabled and shows 


gray text inside the edit area. When the user clicks the “Do It!” menu item, the edit control is 
enabled (can be edited), and displays normal color text inside the edit area. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ‘ 
static HWND hEdit ; 


switch CiMessage) /* process windows messages */ 
{ . 
case wm CREATE: i 
hEdit = CreateWindow ("EDIT", “Edit Me", 
WS_CHILD | WS_VISIBLE | WS BORDER, : 
150, 40, 100, 25, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChEdit, SW_SHOW) ; 
EnableWindow (hEdit, FALSE) ; /* dizeote input */ 
break ; ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) Oe 
C a: : 
case IDM_DOIT: /* User hit the “Do it" menu ites */ 


EnableWindow ChEdit, TRUE) ; /* enable input */ 
break ; 
[Other progra:n lines] | 
ENDDEFERWINDOWPOS OWin2.0 e@Win3.0 mWin3l 
Purpose Completes a rapid movement of a window on the screen. The movement occurs mnen dl this func- 
tion is called. 
Syntax void EndDeferWindowPos(HANDLE hWinPosInfo); 
Description This is the last of the sequence of three functions BeginDeferWindowPos(), DeferWindowPos(), 


and EndDeferWindowPos(). These functions work together to update the position and size of the 
one or more windows in a single screen refresh cycle. The actual movement is done when 
EndDeferWindowPos() is called. 


Uses Animation of windows by repeatedly moving them, or for fast movement of a ae window to a 
new location. 
Returns No returned value (void). 
’ See Also _  BeginDeferWindowPos(), DeferWindowPos() 
Parameters 
hWindPosInfo HANDLE: Handle to the window position data structure created with BeginDeferWindowPos(). 
Example See the example under the BeginDeferWindowPos() function description. 
ENUMCHILDWINDOWS eWin20 mWin30 mWin31 
Purpose Calls an enumeration function for all of the child windows of a parent. 
Syntax. _ BOOL EnumChildWindows(HWND hWndParent, FARPROC lpEnumFunc, LONG /Param); 
Description Enumerates data from all child windows of the parent. You must supply an enumeration function. 


The enumeration function is called once for each child window. The child window's handle and 
the /Param value are passed to the enumeration function each time it is called. Typically, the 
enumeration function collects data for a child window, and stores it in a memory area. /Param 
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Uses 


Returns 
See Also 


Parameters 
hWndParent 


lpEnumFunc 
lParam 


hWndChild 
lParam — 


Example 
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can be used to pass a handle to the memory area to the enumeration function. Note that although 
the child window handle will be different each time the enumeration function is called, the 
lParam value remains the same. 


Retrieving handles to all child windows, or other data associated with the child window. You do 
not need to know how many child windows there are in advance. 


BOOL. TRUE if all child windows have been enumerated, FALSE if not. 
See the aa in the Notes section at the beginning of this chapter. 


HANDLE: Handle to! the parent window. 
FARPROC: Pointer to the enumeration function. 


DWORD: This is the value to be passed to each processing of the enumeration function. 
The enumeration (callback) function must have the form 


BOOL FAR PASCAL EnumFunc (HWND hWndChild, DWORD lParam) 


This function will be called for each child window. You must include the EnumFunc() in the 
EXPORTS portion of the .DEF file. The EnumFunc() must also be registered with Make- 
ProcInstance() prior to use. The enumeration function will return TRUE if enumeration contin- 
ues, FALSE if enumeration stops 

The meaning of the parameters on each call is 


HWND: The handle of a child window. 


DWORD: This is the [Param value passed by EnumChild- 
Windows(). It can be used to pass any data, including a handle 
to a memory block that can be used by the enumeration func- 
tion to store or retrieve data about the child windows. 


This example creates a window with three children, as shown 
in Figure 3-4. When the user clicks the “Do It!” menu item, the 
enumeration function is called to store the names of each of 
the children. The names are then displayed on the parent Figure 3-4.-EnumChild-. 
window's client area. Windows( ) Example. 

Note that the enumeration function keeps expanding the 
memory area allocated, and adds each new child window name to the end of the memory space. 


oles, 
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H Header File 


/* windenum.h x/ 
H#define LOM_DOIT 1 /* menu item id values */ 
H#define IDM_QUIT 2 
/* definitions */ 
Hdefine TITLEWIDE | 20 
typedef struct 
{ 
- GLOBALHANDLE hGMem ; 
int nCount ; 
} ENUMER ; 
/* global variables */ 
int ghinstance ; 


char gszAppName £1] = "WindEnum” ; 


/* funct 


ion prototypes */ 


' long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 
BOOL FAR PASCAL WndEnumFunc CHWND, ENUMER FAR *) ; 


> WindProc() Portion of C Program 
Long EAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD NReraey LONG Corer 
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€ 
static HWND hButton ; 
static HWND hStaticText ; 
static HWND hEdit ; 
static FARPROC lpfEnumProc ; 
static ENUMER - @numer ; 
LPSTR _LpWindName ; 
HDC hdc; , 
int i; 
switch (iMessage) . | /*®* process windows messages af OF audits 
case WM_CREATE:  —. Poe oF t : ph Sas Be 
hButton = CreateWindow (“BUTTON", "Button", ween hg 
7 WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON, 
10, 10, 100, 40, hWnd,- MULL, ghInstance, NULL) ; 
ShowWindow (hButton- SW_SHOW) ; 
/* create and show static text */ 
hStaticText = CreateWindow ("STATIC", "Static Text", 
WS_CHILD | WS_VISIBLE | BS_! PUSHBUTTON, 
150, 10, 100, 15, hWnd, NULL, ghinstance, NULL) ; 
~ ShowWindow ChStaticText, SW_SHOW) ; 
- -/* create and show an edit control */ 
hEdit = CreateWindow C“EDIT!, “Edit Me", 
“te WS_CHILD | WS_VISIBLE | WS_BORDER, 
150, 40, 100, 25, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChEdit, SW_SHOW) ; ‘ 
LpfEnumProc = MakeProcInstance (wndEnumFunc, 
’ ghInstance) ; 
break ; 
case WM_COMMAND: '/*® process menu items */ 
switch (wParam) ¥ . 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
if Cenumer.hGMem) /* if not first time tried */ 
- GlobalFree Cenumer .hGMem) ; /* free the memory */ 
/* saieialize storage area */ 
enumer.hGMem = GlobalAlloc 
(GMEM_MOVEABLE | GMEM_ZEROINIT, 1L) ; 
enumer.nCount = 0 ; 
/* Let Windows run callback func. */ 
EnumChi tdWindows ChWnd, lpfEnuaProc, 
CBWORD) &enumer).; 
hOC. = GetDOC (hWnd) ; /* get ready to output */ 
LpWindName = GlobalLock Cenumer.hGMem) ; /* lock memory */ 
TextOut (hDOC, 10, 100, “EnumChildWindows() found:", 25) ; 
for (i = 0; i < enumer.nCount ; i++) ' {* display window. */ 
{ /* titles found */ 
TextOut ChOC, 15, 125 + (15 * 4), 
CLPSTR) ClpWindName + (i.* TITLEWIDE)), 
Listrlen (lpWindName + (i * TITLEWIDE))) ; 
GlobaltUnlock Cenumer.hGMem) ; /* unlock-memory */ 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} 
; break ; = 
case WM_DESTROY: ° ” hale stop application */ 
GlobalFree Cenumer.hGMem) ; _ /* release all memory */ 
PostQuitMessage (0) ; 
break ; 
defaults . /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 
} 
return COL) ; \ 
> 


ee 3. WINDOWS SUPPORT FUNCTIONS. ¥ 


BOOL FAR PASCAL WndEnumFunc (HWND hWindow, ENUMER FAR *enumer ) 
{ 


“LPSTR lpWindName ; 
char cBuf CTITLEWIDE + 1] ; 


if C!GlobatReAlloc Cenumer->hGMem, a 
- CDWORD) TITLEWIDE * Cenumer~>nCount + 1), 
ss GMEM_ MOVEABLE) ) /* make room for 10 more */ 
return (0) ; /* quit if can't make room */ 
GetWindowText ChWindow, CLPSTR) cBuf, oe /* get title */ 
cBuf CGetWindowTextLength ChWindow)] = - /* add end null */ 
LpWindName = GlobalLock (enumer->hGHen) ; /* Lock the memory area */ 


/* put next name at end ale 
Lstrepy ClpWindName + (Cenumer->nCount) * TITLEWIDE), (LPSTR? cBuf) ; 


GlobalUnlock Cenumer->hGMem) ; /*® unlock the memory area */ 
enumer->nCount++ ; /* keep track of how many */ 
return (1) ; 
> 
EnumProps mWin2.0 mWin3.0 mWin3.1 
Purpose Retrieves all of the entries in the property list of a window. 
Syntax int EnumProps(HWND hWnd, FARPROC IpEnumFunc)); . 
Description Uses a callback function to repeat- 
ediy fetch properties (data) associ- | Pai EuEeaueeners hope 
ated by the window with the ‘eaeeriog 
SetProp() function. 
Uses Allows any amount of data to be as- is ao Lette ities 
sociated directly with the window. 
Returns int. -1 on error. Otherwise returns a pees ee a tek 
the Tast value returned by the call’ } prop2 This data also linked to Window 
See Also EnumChildWindows(), SetProp(), - Figure 3-5. Properties Retrieved from a Window. 
. GetPropQ) 
Parameters | 
hWnd HWND: Handle of the window that has a property list to be enumerated. ~ 
lpEnumFunc FARPROC: Pointer to the enumeration function. The enumeration function must be of the form: ; 
int FAR PASCAL EnumFane (HWND hWnd, LPSTR lpString, HANDLE hData); 
The enumeration function must be listed in the EXPORTS section of the program’s .DEF definition 
file. The enumeration function is called once for each property associated with the window. The 
enumeration function should return zero to stop enumeration, or a non-zero value (1) to continue. 
The parameters passed to the enumeration function have the following meanings: 
hWnd HWND: The handle of the window that has a property list to be enumerated. 
lpSting LPSTR: The character string that was used by SetProp() to name the data. This can also be an 
atom. In this case, the atom is the LOWORD, while the HIWORD is set to zero. Atoms are dis- 
. cussed in Chapter 22, Atom Functions. 
' RDATA . HANDLE: Is a data handle, pointing to the memory where the data is stored. 
Example In this case, two properties are associated with the window. Each of the properties (called 


“Prop” and “Prop2”) is associated with a handle to memory containing a string. The WinProc() 
function demonstrates recovering the property data with both the GetProp() and EnumProp() 
functions. Note that the enumeration function WindPropFunc() must be referenced in the EX- 
PORTS section of the program's .DEF file. When this program executes the “Do It!” menu item, 
the program window appears as shown in Figure 3-5. 


Mg 47 


WINDOWS API BIBLE 


C> Header File 
/* windprop.h */ 


define IDM_DOIT 1 
Hdefine IDM_QUIT 2 

/* definitions */ 
#define PROPSTRINGWIDE 10 
#define MAXPRCP - 30 

/* global variables */ 
typedef struct 
{ 


HANDLE hPropData ; 
char - cPropName CPROPSTRINGWIDE) ; 
} PROPERTY >; — ee 


gPropertyList CMAXPROP] ; 


PROPERTY 
int gnPropertyCount ; 
int ghInstance ; 


char gszAppName CJ = “windprop"” ;_ 

/* function prototypes */ 

long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 
BOOL FAR PASCAL WindPropFunc CHWND hWindow, WORD abunaye 


PSTR pString, HANDLE hData) ; 


o> WindProc() Portion of C Program 


/* menu item id values */ 


tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HANDLE 
FARPROC 


static 
static 
LPSTR 
HDC 
int 
char 


hMemory ;_ 
LpfEnumProc ; 
lpName ; . 
hOdC ; 

i; 

cBuf €128] ; 
switch (iMessage) 
{ 


case WM_CREATE: 


/* process windows messages */ 


strcpy (cBuf, “This data tied to Window") ; 


hMemory = 
(LONG) strlen (cBuf)) ; 
LpName = GlobalLock ChMemory) ; 
lstrcpy (lpName, cBuf) ; 
GlobalUnlock ChMemory) ; 
SetProp (hWnd, 


"“Propi", hMemory) ; 


GlobalAlloc (GMEM_MOVEABLE | GNEM ZEROINIT, 


strepy (cBuf, “This data also Linked to Window") ; 


hMemory = 
i CLONG) strlen (cBuf)) ; 
LpName = GlobalLock (hMemory) ; 
GlobalUnlock ChMemory) ; 
lstrcpy (lpName, cBuf) ; 
SetProp (hWnd, “Prop2", 
LpfEnumProc 
break ; 
case WM_COMMAND: 
switch (wParam) 
{ 
case IDM_DOIT: 
hMemory = 
LpName = 


hdc = GetDC ChWnd) ; 


GlobalALloc (GMEM_MOVEABLE | GMEM_ZEROINIT, 


hMemory) ; 
= MakeProcInstance (WindPropFunc, ghinstance) ; 


/* process menu items */ 


/7* User hit the “Do it” menu item */ 
GetProp (hWnd, “Propi") ; ‘ 
LSC en Onx: ChMemory) ; 
/* get ready to output +f 
TextOut Chdc, 10, 10, “GetProp() found:", 


16) ; 


TextOut ChOC, 15, 25, LpName, Lstrlen ClpName)) ; 


GlobalUnlock Chleasry)-7 
ReleaseDC Chlind, hOC) ; 


/* Link data to window */ 
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gnPropertyCount = 0; ; 
; /* Let Windows run callback func. */ 
EnumProps (hWnd, LpfEnumProc) ; ; 
hoc = GetDC ChWnd) ; © /* get ready to output ne 
TextOut (hDC, 10, 50, “EnumProp() found:", 17) ; 
for (i = 0 ; i < gnPropertyCount ; i++) 
{ /* display titles found */ 
TextOut (hDC, 15, 70 + (15 * i), 
(LPSTR) gPropertyList Cil.cPropName, 
strlen (gPropertyList Cid.cPropName)) ; 
lpName = GlobalLock (gPropertyList fil. hPropData) ; 
TextOut (hOC, 100, 70 + (15 * i), LpName, : 
lstrlen CLpName)) ; 
GlobalUnlock (gPropertyList Cid. hPropData) ; 
} 
ReleasedC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow ChWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
RemoveProp (hwnd, “User Prop") ; 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


BOOL FAR PASCAL WindPropFunc CHWND ne tadoty WORD nDummy, PSTR pString, 
HANDLE hData) 


t 
gPropertyList ConPropertyCount1].hPropData = hData ; 
strepy (gPropertyList CgnPropertyCountd. cPropName, pString) ; 
nb bopertylountrs. . 
return (1) ; 
} 
ENuMTASKWINDOwS | ‘mWin2.0 .mWin3.0 . mWin3.1 
Purpose - Lists all of the top-level windows associated with a task. i 
Syntax BOOL EnumTaskWindows(HANDLE hTask, FARPROC lpEnumFunc, LONG lParam); 
Description Calls an enumeration function to collect the handle for every top-level window associated with a 
task. Tasks are running applications in memory. Windows keeps track of all running tasks in the 
“task handler.” Note that dynamic link libraries (DLLs) are not tasks. Each instance of a program 
is a separate task. 
Returns BOOL. TRUE if all tasks were successfully enumerated, FALSE ifnot. .., . 
See Also EnumChildWindows(), cere) GetWindowTask() 74 ‘ 
Parameters - j 
hTask HANDLE: The handle to the task. Use GetCurrentTask() to retrieve the handle of the currently 
running task, or GetWindowTask() to retrieve the task handle of a specific window. 
lpEnumFunce FARPROC: Pointer to the enumeration function. 
lParam DWORD: The 32-bit value that is to be sent to the callback function each time a task is fund: 


This can be data or a handle to a memory block. 
The enumeration function must be in the form: 
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. BOOLFAR PASCAL EnumFunc (HWND hWnd, DWORD /Param); 


7 The function name must be listed in the EXPORTS section of the program’s .DEF definition 
file. The enumeration function must return TRUE to continue enumeration, FALSE to stop enu- 
meration (such as if an error is detected). The meaning of the 


ai ‘parameters passed to the enumeration function are as follows: 
hWnd ___HWND: Handle to the parent window for a task. This value will = fFounqs> 
. ‘3... be different each time the callback function is called. Found -> File Manager — 
lParam DWORD: The data or pointer that is passed oneach call tothe jFound-> File Manager 


enumeration function. This is the [Param value set when 
EnumTaskWindows() was called. It will be thesameeachtime Figure 3-6. EnumTask- 
the callback function is called. Windows() Example. 


Example Here the enumeration function is used to determine the top- 
level windows associated with the Windows File Manager application. There turn out to be three 
tasks. The first is related to a hidden unnamed window, while the second two are related to a. 
window titled “File Manager.” (See Figure 3-6.) j 


C GENERIC.H Header File 


/* generic.h = */ 


#define IDM_DOIT 1 /* menu item id values */ 
H#define IDM_QUIT 2 
/* definitions */ 
- Adefine TITLEWIDE 20 
typedef struct 
{ 


GLOBALHANDLE hGMem ; 
int nCount ; 
} ENUMER ; ; 
/* global variables */ 
int ghInstance ; 
char gszAppName Ci = “generic" ; 


/* function prototypes */ 
‘ long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) >; 
' BOOL FAR PASCAL WindTaskFunc CHWND, ENUMER FAR *) ; ° 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


static FARPROC LpfEnumProc ; 
_ Static ENUMEP enumer ; 
“HANDLE hTaskWind, hFileMgr ; 
dnt i; 
4 HDC hdc >; 
LPHANDLE LpTaskMem ; 
char _ cBuf £1281, cWindName [64] ; 
switch (iMessage) /* process windows messages */ 
case WM_CREATE: /* tell windows about WindTaskFunc() */ 


ipfEnumProc = MakeProcInstance (WindTaskFfunc, 
ghInstance) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ \ 
case IDM_DOIT: d /* User hit the “Do it" menu item */ 
; \ if Cenumer.hGMem) /* if not first time tried */ 


GlobalFree Cenumer.hGMem) ; /* free the memory */ 
\ /* initialize storage area */ 
enumer.hGMem = GlobalALloc 
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(GMEM_MOVEABLE | GMEM_ZEROINIT, 1L) ; 
enumer.nCount = 0 ; “ 
/* Let Windows run callback func. */ 
hFileMgr = FindWindow (NULL, “File Manager") ; 
hTaskWind = GetWindowTask ChFileMgr) ; 
EnumTaskWindows ChTaskWind, tpfnumProc, 

CDWORD) CLPSTR) Senumer) ; 


hDC = GetDC ChWnd) ;. /* see which tasks were found */ 
lpTaskMem = (LPHANDLE) GlobalLock Cenumer.hGMem) ; 
for (i = 0; i < enumer.nCount ; i++) 


{ 
hTaskWind = * (lpTaskMem + 
Ci. * sizeof CHANDLE))) ; 
GetWindowText ChTaskWind, Suindnaab, 63) ; 
TextOut (hDC, 0, 20*i, cBuf, wsprintf Ceuts 
“Found -> %s", (LPSTR) cWindName)) ; 
} 


GlobalUnlock Cenumer.hGMem) ; 
Released ChWnd, hDC) ; 
break ; 

case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; : 
case WM_DESTROY: /* stop application */ 
Globalfree Cenumer.hGMem) ; /* release memory */ 


FreeProcInstance (tpfEnumProc) ; 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 
} 


/* here is the function to find all of the asks running */ 
oe FAR PASCAL WindTaskFunc (HWND hWind, ENUMER FAR *enumer ) 


“ LPSTR ipMemory, lpDest is 


if C!GlobalReAlloc Cenumer->hGMen, 
(DWORD) sizeof (HANDLE) * (enumer->nCount + 1), 
- GMEM_MOVEABLE) ) /* make room for 1 more */ 

return (0) ;. /* quit if can't make room */ 
LpMemory = GlobalLock Cenumer->hGMem) ; /* tock the mesory area * 
LpDest = LpMemory + Pee numet=-(Gount) * sizeof CHANDLE)) ; 
CHANDLE) *lLpDest = hWind ; = /* store handle to task Hindu x] 
GlobalUnlock (animae-shGnan) ane /* unlock the memory area */ 
enumer->nCount++ ; /* keep track of how many */ 
return (1) ; 


ENuMWINDOWS mWin2.0 mWin30 


_ Purpose Retrieves data on all of the parent windows running on the system. 
, Syntax BOOL EnumWindows(FARPROC [pEnumFunc, LONG lParam); 


Win 3.1 


Description Calls an enumeration function for every parent window running on the system. The enumeration | 


function can collect whatever data is desired from each window as it is processed. 


Uses | . Useful for determining what other applications are running. 
Returns TRUE if all parent windows were enumerated, FALSE if not. 
See Also EnumChildWindows(), EnumTaskWindows() - 

. ' 1 
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. Parameters ——— i A —_ 
lpEnumFunc FARPROC: The procedure instance address of the enumeration callback function. Use 
H MakeProcinstance() to create this pointer. 


lParam — DWORD: The 32-bit value to be passed to the callback function. This can ether be data or a 
pointer. 
The enumeration callback function must be in the follow- 
_ ing format: 2 
BOOL FAR PASCAL EnumFune (HWND hWnd, DWORD | “ Popup. Window’ 
lParam); . Do It! Quit 
The function must be declared in the EXPORTS section of Class value 
the program’s .DEF definition file. The function must return 
TRUE to continue enumeration, FALSE to stop. The param-. 
eters have the following meanings: ~ 
hWnd _ HWND: The window handle for each window enumerated. 


lParam - _DWORD: The lParam value passed in the call to Enum- : ase 
Windows(). This value will be the same each time the enu- Figure 3-7, EnumWindows() 
meration function is called. _ Example. 


Example This example, as shown in Figure 3-7, lists all of the windows active on the screen when the user 
clicks the “Do It!” menu item. 


& WINDENUM.H Header File 


/* windenum. h ef 


define IDM_DOIT too : -  /* menu item id values */ 
H#define IDM_QUIT 2 : 


/* definitions */ 

#define TITLEWIDE 20 
typedef struct : 

{ 


GLOBALHANDLE hGMem ; 


int nCount ; 
} ENUMER ; 
eas /* gtobal variables ap 
int ghInstance ; 
char gszAppName CJ = “windenum" ; 


/* function prototypes *] 
long FAR PASCAL WndProc CHWND, unsigned, “WORD, LONG) ; 
BOOL: FAR PASCAL WndEnumFunc CHWND, ENUMER FAR *) ; 


> WINDENUM. Cc WindProc() Function and Enumeration Function from C Source File 
Long FAR PASCAL WndProc CHWND hwnd, unsigned MeSSAgEZ WORD eee LONG lParam) 
{ . 


static: FARPROC LpfEnumProc ; 
Static ENUMER. -° enumer ; 
LPSTR ; ne. LpWindName ; 
HDC ~ hoe 5 
int : i; 
- switch CiMessage): - ° 7* process windows messages */ 
{ 


‘case WM_CREATE: 
LpfEnumProc = MakeProcInstance (WndEnumFunc, 
ghInstance) ; 
break ;. °° ne 


case WM_COMMAND: oy process menu items */ 
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switch (wParam) 
{ . : bret _ ' 
case IDM_DOIT: /* User hit the "Do it" menu item */ 


if Cenumer.hGMem) /* if not first time tried */ 
GlobalFree Cenumer.hGMem) ; /* free the memory */ 
/* initialize storage area */ 
enumerhGRem: = GlobalAlloc (GMEM_MOVEABLE | GMEM_ZEROINIT, 
1L) ; 
enumer. nCount =O; 
/* let Windows run callback fumes xf 
EnumWindows (LpfEnumProc, CDWORD) Senumer) ; 
hDC = GetDC ChWnd) ; -  {* get ead to output wf 
LpWindName = GlobalLock Cenumer.hGMem) ; /* lock memory “es 
TextOut (hdc, 10, 100, “EnumWindows() founds", 20) ; 
for (i = 0; i < enumer.nCount ; i++) {* display. window *] 
/* titles found */ 
TextOut (hDC, 15, 125 + (15 * i), 
CLPSTR) (LpWindName + (Ci * TITLEWIDE)), 
Lstrlen ClpWindName + (i * TITLEWIDE))) ; 


} 
a 
GlobalUnlock Cenumer.hGMem) ; /* unlock memory */ 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} ba = 
break ; 
case WM_DESTROY: /* stop application */ 
GlobalFree (enumer.hGMem) ; /* release all memory */ : 
PostQuitMessage (0) ; Z 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ;. 
) : 
return OL ; 
} 
00L FAR PASCAL WndEnumFunc (HWND hWindow, ENUMER FAR *enumer) 
{ = 
LPSTR LpwindName ; 
char cBuf CTITLEWIDE + 1] ; 
ut C!GlobalReAlloc Cenumer->hGMem, 
CDWORD) TITLEWIDE * (Cenumer->nCount #1), . 
GMEM_. MOVEABLE) ) /* make room TOE 10 more */ 
return (0) ; . /* quit if can't make room */ 
GetWindowText ChWindow, (LPSTR) cBuf, TITLEWIDE) ; /* get title */ 
cBuf CGetWindowTextLength (ChWindow)] = '\Q' ; /* add end null */ 
lpWindName = GlobaltLock Cenumer->hGMem) ; /* Lock the memory area */ 
“/* put next name at end */ 
Lstrcpy (LpWindName + €Cenumer~>nCount) * TITLEWIDE), (LPSTR) cBuf) ; 
GlobalUnlock Cenumer->hGMem) ; /* unlock the memory area */ 
enumer->nCount++ ; /* keep track of how many */ 
return (1) ; : 
} 
FinpWINDow baa mWin20 .mWin3.0  m Wind! 
Purpose Retrieves a handle to a window. 
Syntax HWND FindWindow (LPSTR ipClassName, LPSTR lpWindowName); 


Description Finds the window’s handle given the class name and/or the window's title. 
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Uses Useful to find specific applications in memory. For example, an application may need to load the 


notepad application if it is not already in memory. 
Returns HWND, a handle to a window. Returns NULL if a match was not found. 
See Also . ChildWindowFromPoint(), WinExec(), GetClassName(), GetWindowText() 
Parameters ot ee 
lpClassName LPSTR: Pointer to a null-terminated string containing the window's class name. If this param- 


eter is NULL, all classes will be searched to find the window name. 


lpWindowName __LPSTR: Pointer to a null-terminated string containing the window's title. If this value i is NULL, 


all names will be searched to find the class name. 
Example This example checks to see if the Windows file manager is running. 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hdc ; /* device contxt handle */ 
’ HWND hWindow ; 
yn switch CiMessage) /* process windows messages *] 
case WM_COMMAND:. /* process menu items */ 
switch (wParam) 
{ , : 
case IDM_DOIT: /* User hit the “Do it" menu item */ 


hWindow = FindWindow (NULL, "File Manager") ; 
hDC = GetDC ChWnd) ; 
if ChWindow) 
TextOut (hDC, 10, 20, . 
“I found the file manager!", 25) ; 


else 
Textout Choc, 10, 20, 
® “File menager not found. ", 22) ; 
ReleaseDc ChWnd, hDdC) ; 
break ; 
[Other program lines] 
FLAsHWINDOW @Win20 wsWin30 Wind) 
Purpose Highlights the window's caption bar if the window is not minimized, or flashes the window’s icon 
: if minimized. 
‘Syntax BOOL FlashWindow (HWND hWnd, BOOL bInvert); 
. Uses . Informs the user that a window needs attention, even if it does not have the input focus. 
_ Returns TRUE if the window was active before the call, FALSE if not. 
See Also  CetFocus(), SetActiveWindow() 
Parameters 
hWnd HWND: Handle to the window to flash. é 
bInvert =~ BOOL: If TRUE, the window is toggled between the active appearance and inactive on each call 
| to FlashWi :dow(). If FALSE, the window is returned to the same state it started (active or in- 
active). 
Related Messages WM_SETFOCUS, WM_ KILLFOCUS 
Example : 
on FAR PASCAL WndProc CHWND hWnd, ‘neianed iMessage, WORD wParam, ‘LONG LParam) — 
switch CiMessage) . /* process windows messages */ 


case WM_COAMAND: ; /* process menu items */ 
_ Switch (wParam) . 
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{ 
case IDM_DOIT: /* User hit the “Do it" menu item */ 
FlashWindow (hWnd, TRUE) ; 
break ; 
[Other program lines] 
GETACTIVEWINDOW ' mWin2.0 mWin30 mWin3.1 
Purpose Finds which parent or popup window is active. . 
Syntax HWND GetActiveWindow(void); . 
Description Retrieves a handle to the parent or popup window that is currently active. Active windows have 


highlighted title bars. Windows are made active by the user selecting the window (the window 
gets the input focus) or by calling SetFocus(). 


Uses In applications with multiple popup windows. Your program can use GetActiveWindow() to find 
which popup is active. 

Returns A handle to the active window. 

See Also SetActiveWindow(), SetFocus() 

Parameters _—None (void). 

Example This example changes the title of the currently active window to “I’m Active!” when the user 


clicks the “Do It!” menu item. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


static HWND hActive ; 
switch (iMessage) . /* process windows messages */ 
{ 

case WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it” menu item */ 
hActive = GetActiveWindow() ; 
SetWindowText ChActive, "I'm Active!") ; 


: break ; 
[Other program lines] 
GeTCLAssINFo OWin2.0 mWin3.0  mWind3.1 
Purpose Retrieves information about a window class. 
Syntax BOOL GetClassInfo(HANDLE kinstance, LPSTR lpClassName, LPWNDCLASS lpWindClass); 
Description Fills in the data in a WNDCLASS structure, based on the instance handle and class name. 
Uses Handy ifyou are modifying a class with SetClassWord() and SetClassLong() as the program oper- 
ates. Eliminates the need to keep track of what is in the operating version of the class. | 
Returns BOOL. Returns TRUE if a class was found and the data loaded, FALSE if not. The class data is | 


copied into WNDCLASS structure pointed to by the pWndClass parameter. The lpszClassName, 
IpszMenuName, and hinstance fields are not filled in by this function. 


typedef struct tagWNDCLASS 
{ 


WORD style; 
LONG ~ CFAR PASCAL *lpfnWndProc)(); 


int cbClsExtra; 
int cbWndExtra; 
HANDLE hInstance; /* no */ 


HICON hicon; 
HCURSOR hCursor; 
HBRUSH hbrBackground; 
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LPSTR LpszMenuName; . /* no */ 


; LPSTR ipszClassName; /* no */ 
} WNDCLASS; 
typedef WNDCLASS *PWNDCLASS; 
typedef WNDCLASS NEAR *NPWNDCLASS; 
typedef, WNDCLASS FAR *LPWNDCLASS; 
See Also . SetClassWord(), SetClassLong(), GetClassLong(), GetClassWord Q, RegisterClass(), Unregister- 
Class() 
Parameters | . 
hInstance — HANDLE: The instance of the program that created the window class. Set to NULL if you would 
like to retrieve information on classes defined by Windows (buttons, list boxes, etc.). 
lpClassName LPSTR: Points to a null- terminated string containing the class name. If the high order word is 
NULL, the function assumes that the low order word is a value returned by the MAKE- 
-INTRESOURCE macro. 
lpWndClass LPWNDCLASS: Points to the memory area reserved to hold the window class data. 
Example This example determines the handle to the brush used to paint the background for the 


application’s window class. 
Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
“ 


static WNDCLASS WndClass ; 
static HBRUSH _ . hbrWindBrush ; 
switch (iMessage) ; /* process windows messages */ 
c 
case WM_COMMAND: - /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* get the class background brush */ 
GetClassInfo (ghInstance, gszAppName, &WndClass) ; 
boc hneerush WndClass.hbrBackground ; 


“ break ; 

[Other program lines] 

GeETCLAssLone. | Win2.0 mWin3.0 mWin3.1 

Purpose . Retrieves a long value from the class structure. , 

Syntax LONG GetClassLong(HWND hWnd, int nIndex); 

Uses Used to retrieve a pointer to the class message processing function. If the class was created 
reserving space for extra four-byte data, GetClassLong() can be used to retrieve it. 

Returns The value requested, usually the message processing function address. 

See Also '  GetClassInfo(), SetClassWord(), SetClassLong(), GetClassWord() 

Parameters 

hWnd ~ HWND: A handle to the window using the class. 


nindex int: Set to one of the values in Table 3-3. 


GCL.WNDPROC Retrieve a far pointer to the window’s message processing procedure. 


GCL_MENUNAME Retrieve a far pointer to a character string containing the menu name. 


Table 3-3. GetClassLong() Index Values. 


56 


Example - 


These index values are defined as negative values in 


3. WINDOWS SUPPORT FUNCTIONS V 


WINDOWS.H. Alternatively, ifyou are retrieving the extra four- Quit 
byte data from the window class, set nJndex equal to the byte * Popup: Window... 
number to retrieve (0, 4, 8...). Dolt! Quit 


This example creates a new window class and uses the class to Class value = 123% 
create a popup window. The class definition contains extra Mtg Wee Be 
space for four bytes (DWORD). These values are set to the inte- 
ger “128” as the popup is created. 

In the popup’s own message processing procedure 
ChildProc(), the class value is recovered and displayed in the 
popup’s client area every time a WM_PAINT message is re- 
ceived. (See Figure 3-8.) 


Figure 3-8. GetClassLong( ) 
Example. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 


WNDCLASS wndclass ; /* the window class */ 

HWND hPopup ; 

switch (iMessage) - /* process windows messages */ 
{ 


“case WM |_CREATE: /* build the child. window when program starts */ 


= CS_HREDRAW { CS_VREDRAW | CS —PARENTDC; 
ChildProc ; 
sizeof (DWORD) ; 
v 
ghInstance ; 
NULL ; 
LoadCursor (NULL, IDC_ARROW) ; 
GetStockObject (LTGRAY_BRUSH) ; 


wndclass.style 
wndclass. lp fnWndProc 
wndclass.cbClsExtra 
wndclass.cbWndExtra- 
wndclass.hInstance 
wndclass.hIcon 
wndclass.hCursor 
wndctass.hbrBackground 
wndclass.lpszMenuName gszAppName ; 
wundclass.lpszClassName “SecondClass" ; 

/* register the window class */ 


hin ni wy we won 


if(RegisterClass (&wndclass)) 
{ : 


hPopup = CreateWindow ("SecondClass", "Popup Window", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 50, 150, 150, hWnd, NULL, ghInstance, NULL) ; 
SetClassLong (hPopup, 0, 123) ; 
ShowWindow (hPopup, SW_SHOW) ; 
} 
break ; 


case WM_COMMAND: /* process menu items */ 


switch (wParam) 


case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 

} 

break ; 


case WM_ DESTROY: /* stop application */ 


default: 


} 
return (OL) ; 


PostQuitMessage (0) ; 
break ; 


/* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 


/* Here is a separate message processing procedure for the child window */ 


long FAR PASCAL ChildProc CHWND hWnd, unsigned iMessage, WORD wParam, 
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' LONG LParam) 


{- = 
char cBuf £128] ; 
int n; 
PAINTSTRUCT ps ; 
switch (iMessage) /* process windows messages */ 
case WM_PAINT: | 
eon ChWnd, &ps) ; 
= Cint) GetClassLong (hwnd, 0) ; . 
yexecue (ps.hdc, 0, 0, cBuf, usprintf (cBuf, 
"Class value = 4d", n)) ; 
EndPaint ChWnd, &ps) ; 
- break ; ‘ } 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
t ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} : 
break ; ; 
default: , /* default windows message processing */. 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} if 
return (OL) ; 
} 
GETCLASSNAME : mWin2.0 wWin3.0 mWin3! 
Purpose. Retrieves the class name upon which a window is based . 
Syntax int GetClassName(HWND hWnd, LPSTR [pClassName, int nMaxCount), 
Description . Copies the class name to a meraory area pointed to by lpClassName. 
Uses =~ —~—s Generally used before GetClassInfo() to load the class name into a string array. 
Returns . The number of characters read. Zero if hWnd is not a valid window handle. 
See Also -—S—sGeetClassInfo() 
Parameters ; : - 7 
‘hWnd ==. ~~ ~—_—sHWND: Handle to the window which was created based on the class. 
lpClassName LPSTR: Pointer to a memory area to hold the class name. 
nMaxCount int: The maximum number of bytes to retrieve. This allows you to keep the class name from 
overflowing the lpClassName area. 
Example This example displays the class name when the user clicks the “Do It!” menu item. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 

char cBuf£[128] ; 

int nLenStr ; 

HDC hDC > 


“switch (iMessage) /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu. items */ 
switch (wParam) 
case IDM_DOIT: /* User. hit the ape it" menu item */ 


nLenStr = GetClassName ChWnd, cBuf, 127) ; 

hDC = GetDCChWnd). ; : 
TextOut (hDC, 10, 10, “The class name is:", 17) ; 
TextOut ChDC, 10, 25, cBuf, nLenStr) ; 
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ReleaseDC (hWnd, hDC) ; 


a break ; 
[Other program lines] 
GETCLAssWorpD mWin2.0 | mWin3.0) Win 3.1 
Purpose Retrieves information from a class. . - , ' ey 
Syntax WORD GetClassWord(HWND hWnd, int nIndex); —— generic v = 
Description Returns two-byte data from a class, Dolt! Quit 
Uses Generally used to retrieve the class cursor, icon, or back- — _ 
ground brush. More efficient than ce if you are 
only retrieving one value. 
Returns The two-byte data value requested. 
See Also GetClassWord(), GetClassLong(), GetClassName(), SetClass- 
Long(), SetClassWord(), GetClassInfo() Figure 3-9. GetClassWord( ) 
Parameters Example. 
hWnd . HWND: The handle of the window that was created based on 
the class. 
nindex 


int: The byte offset for the specific data item. It can be any of the values described in Table 3-4. 


GCW_CBCLSEXTRA _ Retrieve the number of bytes of extra data associated with the class. A secon call to 
~ GetClassWord() can be used to retrieve a word of data. Use an nindex value of 0, 2, 4... for the 
first, second, third... words of extra data. 


GCW_CBWNDEXTRA Retrieve the number of bytes of extra data associated with the window. GetWindowWord) can be 


’ used to retrieve a word of data. Use annindex value of 0, 2, 4... for the first, second, third... .words _ 
of extra data. En 


GCW_HBRBACKGROUND Retrieve a handle to the class backetoune brush. 
GCW_HCURSOR 
GCW_HICON 
GCW_HMODULE 
GCW_STYLE 


Table 3-4. GetClassWord() Index Values. 


Example 


Retrieve a handle to the class cursor. 
- Retrieve a handle to the ciass icon. te a 2, ‘ie. 
~ Retrieve a handle to the class module. | | 

Retrieve the window class style. 


The GCW_ values are defined as negative values in WINDOWS.H. This is how the function differ- 
entiates between positive offsets you supply to retrieve extra data stored with the class and a 
request for a predefined element of class data. 

This example retrieves the class icon, as shown in Figure 3-9, in order to display the icon in the 
window’s client area. 


‘Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 


HICON hIcon ; YS 
HDC hDdC ; 
_ switch CiMessage) a ; /* process windows messages x] 
case WM_COMMAND: — .— , "7 * process menu items */ 
switch (wParam) ve ws 
{ 
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case IDM_DOIT: §/* Paint the program's icon */ 
hicon = Gerclassvord ChWnd, GCW_! HICON) ; 
hoc = GetDC ChWnd) ; 
Drawlcon ChDC, 10, 40, ‘Ateon? ; 
ReleaseDCc snd? hDC) ; 


break ; 

[Other program lines] 

GETCLIENTRECT. @Win2.0 mWin3d.0 mWin3.l 
Purpose - Retrieves a window's client area size. 

Syntax void GetClientRect(HWND hWnd, LPRECT IpRect); ‘ 

Description The client area dimensions are copied into the RECT structure pointed to by /pRect. As client 


coordinates are used, the upper left corner is always 0,0. The bottom right corner gives the client 
area dimensions in device units (pixels). 


Uses . + Use at the start of WM_PAINT refresh cycles to find out how big an area is visible. 

Returns No returned value (void). 

See Also InvalidateRect(), UpdateWindow(), IsIcon(), BeginPaint(), GetWindowExt(), GetWindowRect() 
Parameters 

hWnd . HWND: Handle to the window. 

lpRect LPRECT: Long pointer to a RECT rectangle data structure. 

Related Messages WM_PAINT 

Example _ This example shows an explicit erasure of the client area rectangle. The client rectangle is passed 


to InvalidateRect(). The same functionality can be achieved without using GetClientRectQ), but 
having the second parameter in the InvalidateRectQ) call set to NULL. This causes the entire 
client area to be updated. . 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


noe 


HDC hDC ; F 
RECT rClient ; 
int i; 
o switch CiMessage) /* process windows messages */ 
{ 
case WM_COMMAND: ; /* process menu items */ 
switch (wParam) 
{ : a 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; /* put text in client area */ 
for (i =0; i1< 10; i++) 
C4 
TextOut (hDC, 10, 10 + (i*15), 
4 : “This text will be erased.", 25) ; 
ReleaseDC ChWnd, hDC) ; 
GetClientRect ChWnd, &rClient) ; 
‘InvalidateRect (hWnd, &rClient, TRUE) ; 
UpdateWindow (hWnd) ; /* force WM_PAINT now */ 
break ; 
' [Other program lines] 
GETCURRENTT ASK mWin2.0 wWin30 mWin3.1 
: Purpose Retrieves a handle to the currently executing task. . 
Syntax _ HANDLE B Getoereat esky); 
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Uses 


Returns 
See Also 
Parameters 
Example 


3. WINDOWS SUPPORT FUNCTIONS ¥ 


A task is an application program running on the system. Windows keeps track of all running tasks 
in the “task handler.” Each instance of a program is a separate task: This function is used to 
initialize a callback function made for EnumTaskWindows(). Also used to return the task handle 
for PostAppMessage(). 


HANDLE, a handle to the task executing. ; 
EnumTaskWindows(), PostAppMessage(), GetWindowTask() 
None (void). 


This example is similar to the example under EnumTaskWindows(). In this case, the handle to 
the currently executing task is passed to the enumeration function, rather than the task handle 
for the file manager. The remainder of the program is identical to the example under the 
EnumTaskWindows() function description. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
static FARPROC LpfEnumProc ; ae 
static ENUMER enumer ; ; 
static HANDLE hTask, hFoundTask ; 
int Ai? 
HDC hdc ; 
LPHANDLE LpTaskMem ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_CREATE: /* tell windows about WindTaskFunc() */ 
LpfEnumProc = MakeProcInstance (WindTaskFunc, ghinstance) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the “Do it" menu item */ 
if Cenumer.hGMem) /* if not first time tried */ 
GlobalFree Cenumer.hGMem) ;/* free the memory */ 
/* initialize storage area */ 
enumer.hGMem = GlobalAltloc . 
CGMEM_MOVEABLE | GMEM_ZEROINIT, 1L) ;7 
enumer.nCount = 0 ; 
hTask = GetCurrentTask () ; 
. /* Let Windows run callback func. */ 

. ; EnumTaskWindows ChTask, LpfEnumProc, CDWORD) &enumer) ; 
[Other program lines] . 
GETDESKTOPWINDOW | | OWin2.0 m@Win30 mWin3.l 
Purpose Retrieves the handle of the background window that covers the entire screen. 

Syntax HWND GetDesktopWindow(void); 

Uses Painting on the Windows desktop background. Some specialized utility programs paint on the 
desktop window to provide utilitarian buttons, such as disk icons and button controls, to launch 
applications. : 

Returns A handle to the desktop background window. . 

Parameters ~ None (void). 

Comments The background on which all windows are shown is another window. You can use all painting and 


text output functions on it, as you would the client area of any other window. This area should be 


reserved for special purposes such as screen “saving” and printing programs, as painting on the 
background violates the basic principle of sharing the screen resources between applications. 


WINDOWS APi BIBLE __ 


. Example 


This example prints the string “This text will be on the background.” on the upper left corner of 
the background. It is for demonstration purposes only. Printing text on the pare ute is not.a 
good practice. 


o 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
HDC hdc ; 
HWND hDesktop ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam). 
: 
case IDM_DOIT: ' 7* User hit the "Do it" menu item */ 
hDesktop = GetDesktopWindow () ; 
hDC = GetDC ChDesktop) ; 
TextOut ChDC, 0, 0, 
"This text will be | on the background. ", 36) ; 
ReleaseDC ree hoe) ; 
Sen FE ET See Piet wh ee . break .; i eae 
~ [Other program lines] ¢ 
GETFocus mWin2.0 mWin3.0 mWin3.1. 
Purpose Finds which window has the input focus. 
Syntax HWND GetFocus(void); 
Description Retrieves a handle to the window that has the input focus. The window with the input focus will 
be the next one to receive keyboard input. 
Uses Handy if you have multiple edit controls. Determines which one the user has selected to receive 
text input. 
Returns - HWND, a handle to the window with . . . . 
the input focus. =~ generic fee 
See Also — SetFocus() Dolt! Quit ae 
Paramsienl .°” Nats (void). {oth gut 
Related Messages WM_SETFOCUS, WM_KILLFOCUS , eR ae, Static Text 
Example This example checks which window : 


has the input focus when the user Fdit Me 


clicks the “Do It!” menu item. (See he window with the focus is: Edit Me 
Figure 3-10.) Note that this is as- 


sured to be either the parent win- Figure 3-10. GetFocus() Example. 

dow or one of the children, as . . 

clicking the menu will force the focus back to the application. In other circumstances, the focus 
may be in an outside window when GetFocus() is called. Use SetActiveWindow() to make sure - 
the application is active before calling GetFocus(). 


Long FAR PASCAL WndProc CHWND hWnd, Wastuned iMessage, WORD wParam, LONG lParam) 


C 


static 
static 


HWND hButton ; 
HWND hStaticText ; 


static HWND hEdit ; 
_HWND phocus ; 
HDC a “RDC 3 
static char cBuf- C25] 
switch CiMessage) : /* process windows messages */ 
{ 
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case WM_CREATE: 


hButton = CreateWindow ("BUTTON", “Button", 
WS_CHILD | WS_VISIBLE {| BS_PUSHBUTTON, 
10, 10, 100, 40, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChButton, SW_SHOW) ; 
/* create and show static text */ 
hStaticText = CreateWindow ("“STATIC", “Static Text", 
WS_ CHILD | WS_VISIBLE | BS_PUSHBUTTON, 
150, 10, 100, 15, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChStaticText, SW_SHOW) ; : 
/* create and show an edit control */ 
hEdit = CreateWindow ("EDIT", "Edit Me", 
WS_CHILD | WS_VISIBLE | WS_BORDER, 
150, 40, 100, 25, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChEdit, SW_SHOW) ; 
break ; 


case WM_COMMAND: /* process menu items 7 ae 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
:hFocus = GetFocus () ;° °° alg, ee a ‘ep to 
GetWindowText (hFocus, cBuf, 24) ; 
hDC = GetDC ChWnd) ; 
TextOut ChDC, 10, 65, “The window with the focus is:", 29) ; 
TextOut (hDC, 15, 80, cBuf, strlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 


break ; 

[Other program lines] 
GeETLastActTivEPopup OWin2.0 mWin3.0 mWin3.1 
Purpose Finds the popup window that was active last. 
Syntax HWND GetLastActivePopup(HWND hwndOwner); 
Uses In programs with multiple popup windows. | was Active! 
Returns -  Ahandle to the popup window that was active last. Active win- ya 

dows have their title bars or outline borders highlighted. Will oe : 


return hwndOwner if hwndOwner does not own any popups or 
hwndOwner was the last active window, or if hwndOwner is 
not a top-level window (if it is owned by another window). 


See Also GetActiveWindow(), SetActiveWindow() 

Parameters. ; Figure 3-11. GetLast- . 

hwndOwner HWND: The handle of the parent window that spawned the ActivePopup() Example. 
popup windows. 

Example This example creates a popup child window. When the user clicks the “Do It!” menu item on the 


parent window, a handle to the last active popup window is retrieved. This handle is used to 
change the popup window’s caption to “I was Active!”. (See Figure 3-11.) 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hoc ; /* device context handle */ 

static WNDCLASS wndclass ; /* the window class */ 

static HWND hPopup, hActive ; 

switch (iMessage) ; . /* process windows messages */ 


case WM_CREATE: /* build the child window when program starts */ 


wndclass.style = 
’ CS_HREDRAW | CS_VREDRAW | CS_PARENTDC ; 
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} 


wndclass.tpfnWndProc PopupProc ; 


wndclass.cbClsExtra 0; 
wndclass.cbWndExtra 0; 
wndclass.hInstance ghinstance ; 
wndclass.hIcon NULL ; 


wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.lpszClassName 


LoadCursor (NULL, IDC _ARROW) : 
GetStockObject (LTGRAY_BRUSH) ; 
NULL ; 
“SecondClass" ; 

/* register the window class */ 
if(CRegisterClass (&wndclass)) 
{ 


hare dann 


‘hPopup = CreateWindow ("SecondClass", “Popup Window", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 50, 200, 150, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hPopup, SW_SHOW) ; 


} 
break ; : 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ ‘ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
SetFocus (hPopup) ; 
hActive = GetLastActivePopup (hWnd) ; 
SetWindowText ChActive, “I was Active!") ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 
3} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 


} 
. return (OL) ; 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


/* Here is a separate message processing procedure for the popup window */ 


long FAR PASCAL PopupProc CHWND hWnd, unsigned yaeaenaey WORD uParan, 


C 


LONG LParam) 


return COL) ; 


HDC hoc; /* device context handle */ 
. PAINTSTRUCT ps; . /* paint structure */ 
switch CiMessage) /* process windows messages *7 
case WM_PAINT: /* sdat write in the window af 
hDC = BeginPaintChWnd, &ps) ; 
TextOut (hDC, 1, 1, “WM_ PAINT in Child.", 18) ; 
EndPaint (hWnd, &ps) ; 
break ; 
case WM_ DESTROY: /* stop the apprication */ 
PostQuitMessage CO) ; 
; break ; , . ' 
. default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
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GeTNExTWINDOW , , | gWin20 mWin30 mWin3l 

Purpose Finds parent and child windows. : 

Syntax HWND GetNextWindow(HWND hWnd, WORD wFlag)); 

Description Searches the window manager’s list for the next or previous window. IfhWnd points to a top-level 
window, GetNextWindow() looks for other top-level windows. If hWnd points to a child window, 
GetNextWindow() looks for other child windows. 

Uses To locate child windows in applications with only two or three child windows, EnumWindows() 

and EnumChildWindows() are more efficient where there are many windows. 

Returns HWND, a handle to the next or previous window in the window manager’s list. 

See Also EnumWindows(), EnumChildWindows(), GetWindow() 

Parameters 

hWnd HWND: Handle to a window. If hWnd points to a top-level window, GetNextWindow() looks for 
other top-level windows. If hWnd points to a child window, GetNextWindow() looks for other 
child windows. 

wFlag WORD: Specifies if the handle returned is to be for the next or previous window. It can be either 

GW._HWNDNEXT or GW_HWNDPREV. 
Example , 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


Parameters 


HDC hDC ; 
HWND hNextWindow ; 
char cBufl[25] ; 
switch (iMessage) : /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) > 
case IDM_DOIT: 7* User hit the "Do it" menu item */ 
hNextWindow = GetNextWindow (hWnd, GW_HWNDNEXT) ; 
hDC = GetDC ChWnd) ; 
TextOut ChDC, 10, 10, “The next window is:", 19) ; 
itoa (hNextWindow, cBuf, 10) ; 
TextOut (hdc, 15, 30, cBuf, Lstrlen (cBuf)) ; 
GetWindowText (ChNextWindow, cBuf, 24) ; 
TextOut (hDC, 15, 50, cBuf, Lstrlen (cBuf)) ; 
ReleaseDC (hNextWindow, hDC) ; 
break ; , 
[Other program lines] 
GeTNumT asks —mWin2.0 mWin3.0 Wind 
Purpose Finds the number of tasks running in the system. ° 
Syntax int GetNumTasks(void); 
Description The number of tasks is the number of unique program instances in operation. If more than one 
copy of the same program is operating, each will count as a separate task. 
Uses Used in shell applications such as the Program Manager. The shell can determine if it is the only 
task running by seeing if the returned value from GetNumTasks()is one. 
Returns int, the number of running tasks. 
See Also EnumTaskWindows() . ae 
None (void). 
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Example. This example displays the number of tasks running on the system in the example program’s client 
ee area. The example assumes that the C library STRING.H has been included. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
£ a 


HDC hoc ; 
.char cBuf€25) ; 
, int _ nNumTasks ; 
switch CiMessage) : /* process windows messages */ 
case WM_COMMAND: : /* process menu items */ 
switch CwParam) 
case IDM_DOIT: . /* User hit the "Do it" menu item */ 
nNumTasks = GetNumTasks () ; 
hDC = GetDC ChWnd) ; 
TextOut ChDC, 10, 10, 
“The number of yasks rurining is:", 31); 
itoa (nNumTasks, cBuf, 10) ; 
TextOut (hDC, 15, 30, ‘GBut, eee (cBuf)) ; 
ReleeseDe (hWnd, hdc) ; 
; _ break ; 
[Other program lines] 
GETPARENT | eWin2.0 wWin3.0 mWin31 
Purpose Retrieves a handle to a parent window. 
Syntax HWND GetParent(HWND hWnd), 
Description -_ Windows maintains a table of window handles, and their linkages between parent and children, 


in memory at all times. Any degree of nesting (children of children of children...) is possible. 
GetParent() looks for the parent of the window whose handle is hWnd. 


Uses Useful if a child or popup window has a separate message processing function. GetParent() al- 
lows the child window to retrieve its parent’s handle for sending messages to the parent’s mes- 
sage function. 

Returns HWND, a handle to the parent window. NULL if hWnd does not have a parent. 

See Also ae ac eee GetWindow(). 

Parameters 

hWnd HWND: The starting window's handle. 

Example In this example, the parent window creates a popup suintlaw: The parent sends the popup window 


a WM _USER message when the user clicks the “Do It!” menu item. The WM_USER message has 
the parent’s window handle set as wParam, so that the popup window can print out the parent’s 
name. GetParent() could just as easily been used within the popup window’s message processing 
function to retrieve the parent window! s handle. 


long FAR PASCAL WndProc (HWND hWnd, unsigned inecenge: WORD wParam, LONG LParam) 


GARDE = i> ADC. ad 
static WNDCLASS . wndclass ; 
static HWND " hPopup, hParent ; 
switch (iMessage) - ; , [* Progess windows messages */ 
{ . 


case WM_CREATE: /* build the child window when program starts */ 
wndclass.style CS_HREDRAW | cs. —VREDRAW [| CS_PARENTDC; 
- wndclass.LpfnWndProc ChildProc ; 
wndclass.cbClsExtra 0; 
wndclass.cbWndExtra 0; 
wndclass.hiInstance ghinstance ; 
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wndclass.hIcon 
wndclass.hCursor 


NULL ; 
LoadCursor (NULL, IDC_ARROW) ; 
wndclass.hbrBackground GetStockObject (LTGRAY_BRUSH) ; 
wndclass.lpszMenuName NULL ; 
wndclass.lpszClassName = “SecondClass" ; 

/* register the window class */ 
if(RegisterClass (&wndctass)) 


{ R 
hPopup = CreateWindow ("“SecondClass", “Popup Window", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 50, 200, 150, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hPopup, SW_SHOW) ; 
} : 
break ; . 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it” menu item */ 
‘ hParent = GetParent (hPopup) ; 
/* Tell popup window its parentage */ 
SendMessage (hPopup, WM_USER, hParent, OL) ; , 
break ; . 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} a“ 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; P ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 


- 


} 
return (OL) ; 
} 


/* Here is a separate message processing procedure for the popup window */ 


long FAR PASCAL ChildProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hDC ; 
HWND hParent ; 
char cBuf [£25] ; 
switch CiMessage) /* process windows messages */ 
{ 7 Fi 
case WM_USER: /* message from parent ~ wParam is parent handle */ 


hDC = GetDC (hWnd) ; 

TextOut (HDC, 1, 1,."My Parent window is:", 21) ; 
GetWindowText (CHWND) wParam, cBuf, 24) ; 
TextOut (hDC, 1, 15, cBuf, strlen (cBuf)) ; 
ReleaseDC (hWnd, hDdC) ; 


break ; 
case WM_DESTROY: /* stop the application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 
} om 
return COL) ; 
} 
GETPrRopP . : . mWin2.0 mWin3.0 mWin3.] 
Purpose Retrieves a property (data) associated with a window. 
Syntax | HANDLE GetProp(HWND hWnd, LPSTR lpString); . 
Description Retrieves a handle to the memory area associated with the property named by [pString. 


67 


WINDOWS API BIBLE 


Uses The property functions allow data to be associated with a window. This is an excellent way to deal 


with data that is specific to a certain window, avoiding the need for global data storage. 
Returns HANDLE, a handle to the memory area containing the data. The data must have been previously 
stored with SetProp() 
See Also SetProp(), EnumProp, RemoveProp() 
Parameters _ 
hWnd HWND: Handle to the window which has property data associated with it. 
lpString LPSTR: Pointer to a null-terminated string that contains the name associated with the data. This 


can also be an atom. In that case the high-order word must be set to zero, while the low-order 
‘word should contain the atom value, 


Example _ This example stores a handle to a global memory block as a 
window property. The memory block contains the string “This 
data tied to Window,” as shown in Figure 3-12. When the user Saag generic ered eS 

clicks the “Do It!” menu item, the handle to the memory block 

is retrieved and the string is displayed in the window’s client The window styles for parent: 
area. Real uses of property data are most frequent in applica- Wis CATION 
tions that have a number of similar child windows, such as MDI WS_HSCROLL 
applications (see Chapter 29). Note that deleting the property 
does not remove the data pointed to by the memory handle. Us 
The memory block is deleted separately from the property Figure 3-12. GetProp() 


when processing the WM_DESTROY message. Example. 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 
HANDLE - hMemory ; 
LPSTR LpName ; 
HDC. hDC ; 
char cBuffI = “This data tied to Window"; 
switch (iMessage) /* process windows messages */ : 
{ ‘ 


case WM_CREATE: 
hMemory = GlobalAlloc (GMEM WOVERRLE | GMEM_ZEROINIT, 
(LONG) lstrlen (cBuf)) ; 
ipName = GlobalLock (hMemory) ; 
istrcepy (lpName, cBuf) ; 
’ GlobalUntock (hMemory) ; 
SetProp ChWnd, “User Prop", bMeioRg 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 


2 case IDM_DOIT: /* User hit the "Do it" menu item */ 
hMemory = GetProp (hWnd, “User Prop") ; 
LpName = GlobalLock (hMemory) ; 
hDC = GetDC ChWnd) ; 
TextOut (hDC, 10, 10, "GetProp() found:", 16) ; 
TextOut (hDC, 10, 30, LpName, Lstrlen (lpName)) ; 
! GlobalUnlock ChMemory) ; 
1 ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
pes trey Winey (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
hMemory = GetProp (hWnd, “User Prop") ; 
GlobalFree_ ChMemory) ; 
RemoveProp (hWnd, “User Prop") ; 
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PostQuitMessage (0) ; 


ese : /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
jaca COL) ; 

} 
GeETSysMopaLWInpow . mWin2.0 mWin30 mWin3.1 
Purpose Retrieves a handle to a system modal window. , 
Syntax HWND GetSysModalWindow(void); 
Description System modal windows take over the input focus from all other windows. GetSysModalWindow() 

allows you to get a handle to this window and send it messages if desired. 
Uses Passing messages to system modal windows. 
Returns HWND, a handle to the system modal window. NULL if none exists. 
See Also SetSysModalWindow() 
Parameters None (void). 
Example This example shows the creation of a system modal dialog box. A timer is set up in the parent 


window’s message function that checks every ten seconds if a system modal window exists. Ifso, 


the timer is shut down and the system modal window is sent a WM_DESTROY message. This saves _ 


the user from having to hit the “OK” button to cancel the dialog box. Note that this example will 
delete any system modal window. A more complete application would discriminate between the 
window handle(s) of system modal windows created by the application and those belonging to 
other programs. The GetParent() function is frequently useful in doing these checks. 


® Header File 
/* timer.h’ */ 
#define IDM_DOIT 1 /* menu item id values */ 
Hdefine IDM_QUIT 2 
/* global variables */ 
int ghInstance ; 
char gszAppName [CJ] = “timer” ; 
/* function prototypes */ 
long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 
BOOL FAR PASCAL DialogProc (HWND hDlg, WORD wMess, WORD wParam, LONG lParam) ; 


Note that the resource file contains the dialog box definition. The style DS_SYSMODAL has 
been added to the definition to force the dialog box to be a system modal window. 
> Resource File 
/* timer.rc */ 


#include <windows.h> 
#include “timer.h" 


timer . ICON generic.ico 

timer MENU 

BEGIN ; : - 
MENUITEM “&Do It!" IDM_DOIT 
MENUITEM "SQuit", IDM_QUIT : 

END 


TimerDiatog DIALOG 20, 20, 160, 80 
CAPTION “SYSTEM MODAL" 
STYLE DS_SYSMODAL 


{ 
CTEXT “Timer Example" -1, 0, 12, 160, 10 
CTEXT “This window will go away if you wait.", 
-1, 0, 30, 160, 10 
ICON : “timer” -1, 10, 10, 0, 0 
DEFPUSHBUTTON “OK" : IDOK, 50, 50, 30, 14 
} . 
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© C Listing for WindProc() and Dialog Box Functions 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ , 


HWND hSysModal ; 
static FARPROC LpfnDlgProc ; 
switch (iMessage) _ /* process windows messages */ 
{ ; 
case WM_TIMER: /* kill sys modal window - if any */ 
hSysModal = GetSysModalWindow() ;_ 
if ChSysModal) 
SendMessage (hSysModal, WM_DESTROY, 0, OL) ; 
KillTimer (hWnd, 1) ;. 
SetActiveWindow ChWnd) ; 
break ; . 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: 
7/* set timer 1 to every 10 sec. */ 
if (!SetTimer (hWnd, 1, 10000, NULL)) 
{ _ 
MessageBox (hWnd, "Too many clocks or timers!", 
"Warning", 
MB_ICONEXCLAMATION | MB_OK) ; 
} 
else /* Create a system modal dialog box */ 
t 
LpfnDlgProc = MakeProciInstance (DialogProc, 
ghiInstance) ; 
DialogBox (ghinstance, "TimerDialog", hWnd, 
_lpfnDlgProc) ; 
FreeProciInstance (lpfnDlgProc) ; 
} ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
J} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ;: 
} : 


‘return OL ; 
} 


BOOL FAR PASCAL DialogProc CHWND hDlg, WORD wMess, WORD wParam, LONG LParam) 
{ 


switch CwMess) 


{ 
case WM_INITDIALOG: 
return TRUE ; ‘ 
case WM_COMMAND: /* there is only one command —- quits */ 
ad case WM_DESTROY: 
: ' EndDialog (hDlg, 0) ; 
return TRUE ; 
} 
“peturn FALSE ; 
} 
GETTorWinnow a a eWin2.0 mWin30 mWin3.1 
Purpose Finds the Host child window of a parent. 
_ Syntax HWND GetTopWindow(HWND hWnd); 
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Description 


Returns 


See Also 


Parameters 
hWnd 


Example 


3. WINDOWS SUPPORT FUNCTIONS: 


Windows maintains a list of window handles in memory, including the linkage from parent to 
child. GetTopWindow() can be called repeatedly to find “children of children.” This function 


searches for the first child window in a parent window's internal list of linked child windows. 


HWND, a handle to the top level child window. Returns NULL if the parent does not have child 
windows. 


ChlaWindowFronPoin0, GetWindow() 


HWND: The handle to the parent window. 


This example displays the name to the first child window when the “Do It!” menu item is clicked. 
In this case, there is only one child window: a pushbutton with the window text “Button.” 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


{ : 
static HWND hButton ; 
HWND hTopWindow ; 
HDC hdc ; 
_ char cBuf [25] ; 
switch (iMessage) /* process windows messages */ 
case WM_CREATE: 
hButton = CreateWindow ("BUTTON", "Button", 
WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON, 
10, 10, 100, 40, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hButton, SW_ SHOW) ; 
break ; 
case WM_ COMMAND: . /* process menu items */ 
switch (wParam) 
{ : 
case IDM_DOIT: /* User hit the “Do it" menu item */ 
if ChTopWindow = GetTopWindow ChWnd)): 
{ 
GetWindowText (hTopWindow, cBuf, 24) ; 
hDC = GetDC ChWnd) ; 
TextOut (hDC, 10, 60, "The top window iss", 17) ; 
TextOut (hDC, 15, 75, cBuf, lstrlen (cBuf)) ; 
ReleaseDC ChWnd, hDC) ;. 
} 
break ; 

[Other program lines] 

. GETVERSION . Win2.0 wWin30 gm Win3l 

Purpose Retrieves the version number of Windows and DOS running on the system. 

Syntax DWORD GetVersion(void); ; 

Description — Both the major and minor version numbers (before and after the decimal point) are returned. 

Uses Disabling part of a program if an older version of Windows is in operation. 

Returns DWORD. The high-order word contains the DOS version number. The low-order word eoitaiiis 
the Windows version number. In both cases, the high-order byte of the word contains the minor 
version number, while the low-order byte contains the major version number. For example, Win- 
dows version 3.1 running under DOS 5.0 would be coded 0x 00050103 hexadecimal. 

See Also GetWinFlags() 

Parameters None (void). 

Note This function was incorrectly documented in the Windows 2.0 and 3.0 SDK documents a0 
WINDOWS.H file. 

Example - This example displays the Window's version number when the user clicks the “Do It!” menu item. 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
t 


HDC hoc ; 
char cBuff25] ; 
int nWindVersion, nMajor, nMinor ; 


switch CiMessage) ; /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ ; 
case IDM_DOIT: - /* User hit the “Do it" menu item */ “ee 
\ nWindVersion = (int) GetVersion () ; , 
nMajor = LOBYTE (nWindVersion) ; 
nMinor = HIBYTE paMindversson? ; 
nDC = GetDC ChWnd) ; 
TextOut ChDdC, 10, 10, . 
“The current version of Windows:", 31) ; 
itoa (nMajor, cBuf, 10) ; 
TextOut (hDC, 15, 30, cBuf, Lstrlen (cBuf)) ; 
TextOut (hDC, 25, 30, ".", 1) ; 
itoa (nMinor, cBuf, 10) ; 
TextOut (hDC, 35, 30, cBuf, Lstrlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 
break ;' 


[Other program lines] 


GETWINDOW en mWin2.0 mWin30 mWin31 
Purpose Retrieves a window's handle. . 
Syntax HWND GetWindow(HWND hWnd, WORD wCmmd); 


Description Searches the window manager’s list of parent and child windows for the next entry matching the 
search criteria specified in the wCmd parameter. 


Uses. An alternative to EnumWindows() and EnumChildWindows(). GetWindow() i is simpler to use if 
“there are not very many windows involved in the search. 


Returns HWND, a handle to the window retrieved from the search: NULL if the end of the window 
manager's list was found, or if the function failed (wrong wCmd parameter). . 


See Also EnumWindows(), EnumChildWindows(), EnumTasks() 


Parameters 
hWnd HWND: The handle of the window from which to base the search. 


‘wemd WORD: The search criteria value. This can be any of the values in Table 3-5. 


GW_CHILD. Find the window’s first child window. 


GW_HWNOFIRST Find a child window's first sibling window. If none found, it returns the first top-level window in the 
window manager's list. 
GW_HWNDLAST Find a child window’s last sibling window. If not found, it returns the last top-level window in the 
window manager's list. 
_ GW_HWNDNEXT Returns the next window in the window manager’s list. 
GW_HWNDPREV Returns the previous window in the window manager's list. 
GW_OWNER Returns the owner of a window. 


Table 3-5. GetWindow() Criteria. 
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3. WINDOWS SUPPORT FUNCTIONS v 


This-example creates a child window from the parent window's class when the WM_CREATE 
message is processed. When the user clicks the “Do It!” menu item, the child window handle is 
found with GetWindow(), and its caption string determined with GetWindowText(). The child 
name is displayed in the parent’s client area. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


GWL_EXSTYLE 
GWL_STYLE 


GWL_WNDPROC.__ 


: HDC hDC ; 
HWND hChild, hGotWind ; 
char cBuf £25] ; 
static BOOL bFirstTime = TRUE ; 
switch (iMessage) /* process windows messages */ 
£ 
case WM_CREATE: '  /* build the child window when program starts */ 
if (bFirstTime) 
{ 
bFirstTime = FALSE ; 
hChild = CreateWindow (gszAppName, "Child Window", 
WS_CHILD | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 50, 200, 150, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hChild, SW_SHOW) ; 
} 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) ; 
case IDM_DOIT: /* User hit the “Do it" menu item */ 
hGotWind = GetWindow (hWnd, GW_CHILD) ; 
HOC = GetDC ChWnd) ; /* get device context */ 
TextOut (hOC, 10, 20, "My child is:", 12) ; 
GetWindowText (hGotWind, cBuf, 24) ; 
TextOut (hDC, 15, 40, cBuf, strlen (cBuf)) ; 
ReleaseDC (hWnd, hDc)> ; /* release device context */ 
break ; 
[Other program lines] 
! 
~ GETWINDOWLONG | mWin2.0 mWin30 mWin31 
Purpose. Retrieves a long value from a window’s data. 
Syntax LONG GetWindowLong(HWND hWnd, int nIndex); . 
Uses Useful where one or more windows has been subclassed by modifying the basic class structure 
with SetWindowLong(). Also used tv retrieve 32 bit values saved with SetWindowLong(). 
Returns The LONG value specified. 
See Also GetWindowWord(), SetWindowLong(), SetWindowWord(), GetClassLong(), GetClassWord() 
Parameters Bo 
hWnd HWND: The window’s handle.~ = ~— 
nIndex ‘int: The index to the value to retrieve. This can be any of the values in Table 3-6. 


Meanin: 


Retrieve the extended window style. 


Retrieve the window style. 
Retrieve a long pointer to the window’s message processing funetion. 


Table 3-6. GetWindowLong() Index Values. 
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These GWL_ values are all defined as negative offsets in 


WINDOWS.H. To retrieve extra four-byte data associated with =: generic pr [= 
a window's class structure, use a positive byte offset for 
nIndex. 0 for the first value, 4 for the second, etc. The window styles for parent: 
Related Messages GetWindowWord(), SetWindowLong(), SetWindowWord() Winey a 
S_HSCROLL 
Example This example displays the style parameters of the main win- = 
dow when the user clicks the “Do It!” menu item. (See Figure : 
3-13.) _ Figure 8-18. GetWindow- 


Long() Example. 
long FAR PASCAL WndProc CHWND hWnd, ‘unsigned iMessage, WORD wParam, LONG LParam) 
t 3 ; 


- HOC. hoc ; 
char cBufl25] ; 
LONG lStyle ; 


switch (iMessage) /* process windows messages */ 
i ~~ 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
UStyle +: GetWindowLong (hWnd, GWL_STYLE) ; 
hDC = GetDC (hWnd) ; 
TextOut ChDC, 10, 10, 4 
‘“The window styles for parent:", 29) ; 
if (lStyle & WS_CHILD) 
TextOut (hDC, 15, 20, "WS_CHILD", 8) ; 
df ClStyle & WS_CAPTION) 
TextOut (hDC, 15, 30, "WS_CAPTION", 10) ; 
if (tStyle & WS_HSCROLL) 
TextOut (hDC, 15, 40, "WS SHB ORO 10) ; 


/* etc */ 
ReleaseDC (hWnd, hDC) ; 
break j 
[Other program lines] - 
GETWINDOWRECT | | me Win2.0 mm Win3.0) mWin3.1 
Purpose Retrieves a window's outer dimensions. , 
Syntax void GetWindowRect(HWND hWnd, LPRECT lpRect); 
Description Copies the dimensions of the bounding rectangle that exactly encompasses the window into the 


rectangle structure pointed to by /pRect. The dimensions are in screen coordinates (pixels mea- 
sured from the upper left corner of the screen). 


Uses Window movement and sizing. 
Returns No returned value (void). 
See Also GetClientRect() 
Parameters . 
hWnd HWND: A handle to the window. 
. lpRect . LPRECT: A pointer to a RECT structure that will contain the window’s bounding rectangle. The 


points will be computed in screen coordinates, with 0,0 being the upper left corner of the screen. 
Related Messages WM_SIZE 


Example This example moves a window across the screen diagonally. GetWindowRect() is used to provide 
; the initial window position and size. — 
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long FAR PASCAL WndProc C(HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


RECT rWindow ; 


int Paap 38 
switch (iMessage) . /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
GetWindowRect ChWnd, &rWindow) ; 
for (i = 0; i < 10 ; itt) 
{ 
MoveWindow (hWnd, rWindow. left + i*10, 
rWindow.top + i1*10, 
rWindow.right + i*10, 
rWindow. bottom + i*10, TRUE) ; 
} 
break ; 
[Other program lines] 
GETWINDOWTASK | mWin2.0 mWin3.0 mWin3.1 
Purpose Retrieves a handle to a task. Je 
Syntax HANDLE GetWindowTask(HWND hWnd); [— generic Parent [> [= 
‘ i ’ ‘ Ki it 
Description A task is any operating program. Each instance of a program bok St oe 
running is a separate task. This function finds the task Tanele 
when given the window handle. | Popup Window 
Uses — Used to determine the task handle, when given the window | a—_erimena 
handle. This may be done before calling EnumTaskWindows() 
to provide the hTask parameter. 
_ Returns ’ HANDLE to the task. 
See Also. EnumTaskWindows() | | Figure 3-14. GetWindow- 
Parameters Task() Example. 
hWnd HWND: The window’s handle. 
Example This example creates a parent window Pre a popup window. Both windows display their task 


handle number. Figure 3-14 provides a graphical example illustrating that all of a top-level 
window’s child windows are part of the same task. 

The popup window’s message processing function ChildProc() must be listed in nthe EXPORTS 
section of the program’s .DEF definition file. A function prototype should also be placed in the 
program’s header file. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ P 


PAINTSTRUCT ps ; 

WNDCLASS wndclass ; 

HWND hPopup ; 

HANDLE hTask ; 

char . cBuf £128] ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_CREATE: /* build the child window when program starts */ 
wndclass.style 
= CS_HREDRAW | CS_VREDRAW | CS_PARENTDC ; 
wndclass.lpfnWndProc = ChildProc ; 
wndclass.cbClsExtra =0; 
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wndclass.cbWndExtra 


0; : 
wndclass.hInstance ghInstance ; 
wndclass.hIcon NULL ; 


wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.tpszClassName 


LoadCursor (NULL, IDC_ARROW). ; 
GetStockObject (LTGRAY BRUSH) ; 
NULL ; 
“SecondClass" ; 
/* register the window class */ 


tne uu wou 


if(RegisterClass (&wndclass)) 


{ 
3 hPopup = CreateWindow ("SecondClass", "Popup Window", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS._CAPTION, 
110, 50, 200, 150, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hPopup, SW_SHOW) ; 
} 
break ; 


case WM_PAINT: 
BeginPaint. (hWnd, &ps) ; 
hTask = GetWindowTask (hWnd) ; 
TestOut (ps.hdc, 0, 0, cBuf, oh a seeut, 

My ‘task number is: %d", hTask)) ; 

EndPaint’ ChWnd, &ps) ; 
break ; 

case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ : 

case IDM_QUIT: 
: DestoryWindow ChWnd) ; 


DESSK 7 
} 
break. ; 
case WH_! DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break $ : ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; ° 


/* Here is a separate message processing procedure for the popup window * 


Long FAR PASCAL ChildProc CHWND hWnd, unsigned iMessage, WORD wParam 
LONG LParam 


PAINTSTRUC ps 


HANDL : hTask 
cha cBuf £128) 
switch (iMessage ; . _° fk process windows messages * 


case WM_PAINT 
BeginPaint ChWnd, &ps) 
hTask = GetWindowTask (hWnd) 
TextOut (ps.hdc, 0, 0, cBuf, wsprintf (cBuf 
“My task number is: ud", hTask)) 
EndPaint (hWnd, &ps) 


break 
case WM_DESTROY /* stop the application * 
PostQuitMessage (0) 
~ break 
default /* default windows message processing * 


return DefWindowProc ChWnd, iMessage, wParam, lParam) 


return (OL) 
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GETWINDOWTEXT eWin2.0 mWin3.0 mWin3.1 

Purpose — Retrieves a window's caption (title string) 

Syntax int GetWindowText(HWND hWnd, LPSTR lpString, int nMaxCount); 

Uses For parent, popup, and child windows, the title string shows above the menu bar. For buttons, the 
title string shows in the center of the button. 

Returns The number of characters copied. Zero if there is no caption. 

See Also SetWindowText(), GetWindowTextLength() 

Parameters . 

hWnd HWND: The handle to the window with a title. . 

lpString — LPSTR: A pointer to the memory area that will contain the title string. 

nMaxCount int: The maximum number of characters to copy. This helps avoid overrunning the end of the 


character buffer set aside to hold the title string. 


Example _This example displays the title of the window in the window’s client area. 

; / 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hDC ; 
char cBufl25] ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
GetWindowText (hWnd, cBuf, 24) ; 
hDC = GetDC (hWnd) ; 
TextOut (hDC, 10, 10, "The window title for the parent:", 
32) ; 7 
TextOut ChDC, 15, 25, cBuf, GetWindowTextLength (hWnd)) ; 
ReleaseDC (hWnd, hDC) ; ‘ 


break ; 
[Other program lines] 
GETWINDOWTEXTLENGTH mWin2.0 mWin30 3 mWin3.l 
Purpose Finds the number of characters in a window’s title string. 
Syntax int GetWindowTextLength(HWND hWnd); 
Uses Used prior to GetWindowText() to set up a memory buffer big enough to hold the title string. 
Returns int, the number of characters in the window's title. This can be zero if the window does not have 
a title. 
See Also GetWindowText(), SetWindowText() 
’ Parameters 
hWnd HWND: The handle of the window with the title. . 
Example See the previous example under the GetWindowText() function description. 
GETWINDOWWorD _ mWin2.0 mWin380 mWin3l 
Purpose Retrieves a two-byte value from a window's data. —_ : 


Syntax WORD GetWindowWord(HWND hWnd, int nIndex), 
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Uses . - Most commonly used to get the window’s instance handle (hInstance). Can also be used to deter- 
. mine the ID value of a child control, or retrieve 16-bit data stored with the window data by 

SetWindowWord(). 

Returns WORD, the value specified by the nJndex parameter. : 

See Also GetWindowLong(), SetWindowWord(), SetWindowLong() 

Parameters 

hWnd HWND: The handle to the window. 

nlndex int: Specifies which value to retrieve. This can be any of the values described in Table 3-7. 


"Valve 


RANE eee ‘ 


"Meaning 


WW_HINSTANCE Retrieve the window’s instance handle. 


GWW_HWNDPARENT Retrieve the handle of the parent window. 


GWW_ID ‘ Retrieve a child window's control ID value. 
Table 3-7, GetWindowWord() Index Values. : | 


The GWW_ index values are defined as negative numbers in WINDOWS.H. To retrieve extra 
16-bit data stored with the window's class definition, use a positive offset for nJndex. 0 for the 
first entry, 2 for the second, etc. The amount of space available is set by the cbWndExtra element 
of the WNDCLASS structure passed to RegisterClass() when the class was registered. 16-bit data 
is added to the extra data area with SetWindowWord(). : 


Example 
Long FAR PASCAL WndProc CHWND hWnd, junsigned iMessage, WORD wParam, LONG LParam) 
{ | ; 


HDC hoe; 

char cBuf£25] i 

HANDLE hInstance ; ‘° 

switch CiMessage) : . /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hInstance = GetWindowWord (hWnd, GwW_HINSTANCE) ; 
hDC = GetDC ChWnd) ; 
TextOut ChDC, 10, 10, 

"The instance handle of the parent:", 35) ;> 

itoa (hInstance, cBuf, 10) ; 
TextOut C(hDC, 15, 25, cBuf, strlen (cBuf)) ; 
_ReleaseDC (hWnd, hDC) ; | 


. ; break ; 
[Other program lines] 
GETWINFLAGS mWin2.0 mWin30 mWin3.1 
Purpose Determines what computer CPU and memory model are in operation. 
Syntax DWORD GetWinFlags(void); . 
Uses Convenient for determining the approximate performance of the system. 
Returns . DWORD value with the parameters encoded as bit values. They may be any of the values de- 


scribed in Table 3-8. - 
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WF_80x87 The system has a math coprocessor. 

WF_CPU086 The system has an 8086 CPU. 

WF_CPU186 The system has an 80186 CPU. 

WF_CPU286 The system has an 80286 CPU. 

WF._CPU386 The system has an 80386 CPU. 

WF_CPU486 The system has an 80486 CPU. 

WF_ENHANCED Windows is running in Enhanced Mode. 

WF_LARGEFRAME Windows is running with the EMS large-frame memory configuration. 

WF_PMODE ~ Windows is running in protected mode. This is always set if the mode is WF_ENHANCED or 
WF_STANDARD. 

WF_SMALLFRAME Windows is running with the EMS small-frame memory configuration. 

WF_STANDARD - Windows is running in standard mode. 


Table 3-8. GetWinFlags() Flags. 


You can detect if Windows is running in Real Mode by verifying that neither WF_ENHANCED 
nor WF_STANDARD has been set. 


See Also GetVersion() 
Parameters None (void). 
kxample 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) ‘ 
{ : 


HDC hdc ; 
DWORD dwWinFlags ; 
“switch (iMessage) /* process windows messages */ 
{. ° 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it” menu item */ 
dwWinFlags = GetWinFlags () ; 
hdc = GetDC (hWnd) ; /* get device context */ 
TextOut ChDC, 10, 20, “GetWinFlags Found:", 18) ; 
if (dwWinFlags & WF_CPU286) : 
TextOut ChDC, 10, 40, "80286 CPU", 9) ; 
else if (dwWinFlags & WF_CPU386) ; 
TextOut ChDC, 10, 40, "80386 CPU", 9) ; 
else if (dwWinFlags & WF_CPU486) 
TextOut ChDC, 10, 40, "80486 CPU", 9) ; 
if (dwWinFlags & WF_ENHANCED) 
TextOut (hDC, 10, 60, “Enhanced Mode", 13) ; 
if (dwWinFlags & WF_80x87) 
TextOut (hDC, 10, 80, "Math Coprocessor", 16) ; 
ReleaseDC (hWnd, hDC) ; /* release device context */ 
break ; 
[Other program lines] 
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IsCHILD 
Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
hWndParent 


hWnd 
Example 


Determines if a window is the child of a given parent window. 
BOOL IsChild(HWND hWndParent, HWND hWnd); 


mw Win 2.0 


@ Win 3.0 


eWin3.l | 


Finds out if hWnd is the direct descendant of the hWndParent window. Windows maintains the 
relationship of child windows to their parents in memory at all time. Descendents may also be 


popup windows. 


Useful in determining the rolacianste of a series of child windows located with 
EnumChildWindows() 


BOOL. TRUE if hWnd is a child of hWndParent, FALSE if not. 


EnumChildWindows(), ChildWindowFromPoint(), WindowFromPoint() 


HWND: A handle to the potential parent window. 
HWND: A handle to the child window to be checked as a descendant of hWndParent. 
. The parentage of the child window is checked and displayed in the parent’s client area when the 


user types the “Do It!” menu item. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned INes Sages, WORD wParam, LONG lParam) 


hDC 
hChild ; 


cBuf1 £251, cBuf2 C25] ; 


bIsChild ; 


case WM_CREATE: 


if (bFirstTime) 


break ; 


bFirstTi 
hChild 


case WM_COMMAND: 
switch (wParam) 


case IDM_DOIT: 


{ 
HDC 
static HWND 
char 
static BOOL 
BOOL 
switch (iMessage) 
{ 
{ 
} 
if 
if 
[Other program lines] 
IsIconic 
Purpose 


- Syntax 


bIsChild = 


bFirstTime = TRUE ; 


/* process windows messages */ 


/* build the child window when program starts */ 


me = FALSE ; 


= CreateWindow (gszAppName, “Child Window", 


WS_CHILD | WS_VISIBLE | WS_BORDER | WS_CAPTION, 


100, 50, 200, 
ShowWindow ChChild, SW_SHOW) ; 


/* process ;imenu items */ 


/* User hit the "Do it" menu item */ 
IsChild (hWnd, hChild) ; 


150, hWnd, NULL, ghInstance, NULL) ; 


GetWindowText ChWnd, cBuf1, 24) ; 

GetWindowText (hChild, cBuf2, 24) ; 
hDC = GetDC ChWnd) ; 
TextOut C(hDC, 10, 10, cBuf2, strlen (cBuf2)) ; 
if (bIsChild) 


else 


TextOut (HDC, 


TextOut ChDC, 10, 30, 


10, 30, "Is a child of:", 14) ; 


TextOut (hDC, 15, 50, cBuft, strlen (cBuf1)) ; 
ReleaseDC ChWnd, hDC) 


break ; 


Checks to see if a window is minimized 
BOOL IsIconic(HWND hWnd); 
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A 


/* retease device context */ 


@ Win 2.0 


@ Win 3.0 


“Is NOT. a child of:", 18) ; 


m Win 3.1 


Deseription - 


Returns 


Parameters 
hWnd 


3. WINDOWS SUPPORT FUNCTIONS ¥ 


Normally, windows that are to be minimized have an icon as part of their class definition. When 
the window is minimized, the icon is displayed. If the class definition has NULL for the class icon, 
the program is expected to paint in the little bit of client area that is displayed when the window 
isminimized. — 

Handy in processing WM_! PAINT messages. If the window is minimized, a separate painting rou- 
tine can be used. — 


BOOL. TRUE if the window is minimized, PALSE if not. 


IIWND: The handle to the window which may be minimized. 


Related Messages WM_PAINT, WM_SIZE 


Example | 


In this example, the parent’s window class does not have an icon. Instead the program detects if 
the window is iconized and writes different text if it is during the WM_PAINT cycle. 


#include <windows.h> /* window's header file ~ always included */ 
#include “generic.h" /* the application's header file */ 


. int PASCAL Wintain (HANDLE hInstance, HANDLE hPrevInstance, LPSTR LpszcadLine, 
int nCmdShow) : : 


c 
HWND hWnd ; - /* a handle to a message */ 
ASG _ msg; /* a message */ 
WNDCLASS wndclass ; /* the window class */ 
ghInstance = hinstance ; /* store instance handle as global var.: */ 
if CthPrevinstance) 7 /* load data into window class struct. */ 
{ : 
_wndclass.style = CS_HREDRAW | CS_’ VREDRAW. ; 
wndclass. lpfnWndProc = WndProc ; 
wundclass.cbClsExtra =0; , / 
wndclass.cbWndExtra =0; 
wndclass.hInstance = hInstance ; 
wndclass.hIcon = NULL ; P 
wndclass.hCursor = LoadCursor (NULL, IDC_. ARROW) 3 
wndclass.hbrBackground = GetStock®bject (WHITE, BRUSH) ; 
wundclass.tpszMenuName = gszAppNdme ; 
wndclass.lpszClassName =  9szAppName ; 
nes /* register the window class */ 
if C!RegisterClass (ayndelass)) 
: ‘return FALSE ; 
hWnd = CreaceWindow ( | /* create the program's window here */ 
gszAppName, /* class name */ 
gszAppName, /* window name */ 
WS_OVERLAPPEDWINDOW, /* window style */ 
CWLUSEDEFAULT, | , /* x position on screen */ 
CW_USEDEFAULT, /* y position on screen */ 
CW_USEDEFAULT, /* width of window */ 
Cw. _USEDEFAULT, ‘ /* height of window */ 
NULL, /* parent window handle (null = none). */ 
NULL, A. % - /* menu handle (null = use class menu) */ 
hinstance, /* instance handle */ 
NULL) ; /* Lpstr (null = not used) */ 
ShowWindow ChWnd, nCadShow) ; *s 
UpdateWindow ChWnd) ; /* send first WMH_PAINT message */ 
while (GetMessage Camsg, NULL, 0, 0)) re ' /* the message loop */. 


TranslateMessage (Gaig)?: 
ppsapartneessae acy 


WINDOWS API BIBLE _ 


return as Mnerae ; 1s 
% * 


Long FAR PASCAL WndProc CHWND hWnd, unsigned ineseege: WORD wParam, LONG lParam) 
ff. ; 

i. HDC DC | 
 PAINTSTRUCT psPaintStruct ; 


switch (iMessage) /* process: windows messages */] 


case WM_PAINT: 
hDC = BeginPaint (hWnd, gpsPaintstruct) ; 
if CIsIconic ChWnd)) 
Textout Choc, 1, 1, “teon", 4); 
else 
Textout: (hoc, 10, 10, "Not jconized nows", 17); 
EndPaint ChWnd, epsPaintStruct) ; , 
break ; 
case WM_ COMMAND: hae i process menu items */ 
switch (wParam) - 


case IDM_DOIT: | - /* User hit the "Do it" menu item */ 


CloseWindow hwnd) 3: /* minimize window */ 
. break ; 
case IDM_QUIT: - : /* send end of application message ry; 
' DestroyWindow Chiind). ; 
break ; : 
} 
break ; oo ee 
- case WM_DESTROY: : ‘/* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
~ peturn DefWindowProc (hWnd, iMessage, wParam, \Param) ; 
>. a oS 
’ return COL) ; 
IsWinpDow = | = mWin2.0 mWin3.0 mWin31 
Purpose _ Checks to see if a window handle still points to a valid window. 

Syntax . ~ BOOL IsWindow (HWND hWnd); . 
Description . Windows keeps a list of all active windows in the system. This function compares the handie to 
the list of windows to see if the window exists. oO, 

Uses «Useful in applications where the user can destroy child windows or popups. 
Returns _— BOOL. TRUE if hWnd refers to a valid window, FALSE if not. 
See Also — IsWindowEnabled(), IsWindowVisible(), DestroyWindow() 
- Parameters - . 
hWnd . . HWND: The window handle to check. 
Example 7 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
aay es . 


HDC hOC ; 

static HWWD hchild ; 

char. cBuf C25] ; 

static BOOL bfirstTime = TRUE ; 

BOOL biswWindow : 

Se Rr chi ines sage? Is process windows messages a]. 


caseWM_CREATE: /* build the child window when program starts */ 


ge 


areas 
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if (bFirstTime) 


{ 
bfirstTime = FASLE ; 
hchild = CreateWindow (gszAppName, "Child Window", 
WS_CHILD | WS_VISIBLE | WS_BORDER | WS_CAPTION 
/ 100, 50, 200, 150, hWnd, NULL, ghInstance, NULL); 
; ShowWindow ChChild, SW_SHOW) ; 
+. a. ‘ 
\ break ; 
case WM_COMMAND: ‘ /* process menu items */ 
switch (wParam) 
£.° nese : 
case IDM.DOIT: _./* User hit the "Do it" menu item */ 
hDC = GetDdC ChWnd) ; 
. bIsWindow = IsWindow (hChild) ; 
if (bIlsWindow) 
15 GetWindowText (hChild, cBuf, 24) ; 
a : TextOut (hdc, 15, 20, cBuf, strlen (cBuf)) ; 
TextOut (hOC, 10, 40, "was created OK.", 15) ; 
} 
; ReleaseDC (hWnd, hDC) ; 
Beas break ; 
[Other program lines] 
ISWINDOWENABLED @Win2.0 sWin3.0 Win 3.1 
Purpose Checks to see if a window is enabled for keyboard input. 
Syntax BOOL IsWindowEnabled(HWND hWnd); 
Uses Most often used with edit controls to see if the control is enabled for keyboard input. 
Returns BOOL. TRUE if the window is enabled, FALSE if not. 
See Also EnableWindow(), IsWindowVisible(), IsWindow() 
Parameters 
hWnd HWND: A handle to a window (or child window control). 
Related Messages WM_ENABLE 
Here the edit control is initially disabled. The text in the edit control shows up grayed and cannot 


be edited. After the user clicks the “Do It!” menu item, the control is enabled and can be edited. 


tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
.¢ 


static HWND hEdit ; 
static BOOL bFirstTime = TRUE ; 
en switch (iMessage) ; /* process windows. messages */ 


case WM_CREATE: - 
if (bFirstTime) 


{ ; : 
hEdit = CreateWindow ("EDIT", "This is edit text", 
WS_CHILD | WS_VISIBLE, 
10, 10, 100, 40, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChEdit, SW_SHOW) ; 
EnableWindow (hEdit, FALSE) ; /* starts disabled */ . 
bFirstTime = FALSE ; 
4 ; 
break ; . 
- case WM_ COMMAND: /* process menu items */ 
ou (wParam) 
- case IDM_DOIT: /* User hit the “Do it" menu item */ 
if C!IsWindowEnabled ChEdit)) /* if disabled be oe 
.EnableWindow (hEdit, TRUE) ; /* anable */ |. 
break ; 


[Other program lines] 
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IsWinpowVisIBLe : | mWin20 mWin30 mWin3.l 
Purpose Checks to see if a window has been nate visible. : 
Syntax BOOL IsWindowVisible (HWND hWnd); 
Description Windows are made visible by calling ShowWindow(). IsWindowVisible() will return TRUE for any 
window that has been activated with ShowWindow(), even if the window i is completely obscured ° 
-on the screen by other windows. 
Uses Use if you want to reduce Window’ 's overhead workload by not “showing” the window until iti is 
needed, or if you need to know if the window was hidden with a call to ShowWindow(). 
Returns BOOL. TRUE if ShowWindow() has displayed the window, FALSE if not or if the window does not - 
exist. 
See Also ShowWindow() 
Parameters . 
—AWnd. HWND: A handle to the window to check. 
Related Messages WM_CREATE 
_Example This example toggles a child window from hidden to visible each time the “Do It!” menu item is | 
. 88 clicked. 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
_ HDC hDC ; 
static HWND “hChild ; 
~ char -- cBuf [25] ;. 
static BOOL bFirstTime = TRUE ; 
BOOL bIsVisible ; — 
switch (iMessage) /* process windows messages */ 
{ : 2 
case WM_CREATE: | /* build the child window when program starts */ 
if (bFirstTime) ‘ Se 
£ 
brirstTime = FALSE ; ; 
hChild = creatawindow (gszAppName, "Child Window", * 2s 
: - WS_CHILD | WS_VISIBLE | WS_BORDER | WS _CAPTION, 
100, 50, 200, “450, hwnd, NULL, abInstance,: NULL) ; 
; ShowWindow Chehitd, SW_ SHOW). ; 
} 
‘break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ ; 
case IDM_DOIT: /* veer hit the "Do it" menu item ry) 
hDC = GetDC ChWnd) ; 
bIsVisible = IsWindowVisible Chchild) ; 
if cbtetiashte) 
.f 
GetWindowText Chchild, cBuf, 24) ; 
TextOut Choc, 10, 20, cBuf, strlen (cBuf)) ; 
TextOut (hdC, 10, 40, “is now visible.", 15) ; 
TextQut ChDC, 10, 60, “Now hiding Child...", 19) ; 
ShowWindow (hchild, SW ke 
} 
else ; 
hal, TextOut (hdc, 10, 20, 
; seni window not visible.", 25) ; 
; ReleaseDC ChWnd, hDC) ; /* release device context 7, 
ne: break ; % 
[Other program lines] 


3. WINDOWS SUPPORT FUNCTIONS ¥ 


IsZoomMED | | wWin2.0 mWin3.0 mWin31 
Parpose Checks to see ifa window! is maximized. 

Syntax BOOL IsZoomed(HWND hWnd); 

Uses Many programs do not show the full client region data if their window is not maximized. This 

. function checks to see if the window fills the screen. 

Returns . BOOL. TRUE if the window is maximized, FALSE if not. 

See Also. _—_IsIconic(), MoveWindow(), CloseWindow(), Opentcon() 

Parameters - 

hWnd HWND: A handle to the window to check. 

Related Messages WM_SiZE 
‘Example = —=—The main window displays a text string indicating if the window is maximized or not when the 


user clicks the “Do It!” menu item. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) - 
t 


HOC 83 ssh gx 
switch CiNessage) . /* process windows messages */ 
case WM_ COMMAND: /* process menu items */ 
switch. Lurene? : : 
case 1M_porT: ' /*/User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
if (IsZoomed ChWind)) 
TextOut Choc, 10, 10, 
“Window is now maximized.", 24) ; 
else = 
TextOut choc, 10, 10, 
“Window is NOT maximized, ", 24) ; 
ReteaseDC Chiind, hDC) ; : 
break ; . : ¢ 
[Other program lines] 
MoveWinpow | , wWin20 eWin3.0 mWin3l 
Purpose Moves or resizes a window 
Syntax void MoveWindow(HWND hWnd, int.X, int Y, int nWidth, int nHeight, BOOL bRepaint); 
Description Sends WM_SIZE and/or WM_MOVE messages to the window's message processing function. The 


_ nWidth and nHeight parameters are passed with the WM_SIZE message. The X,Y values are 
‘passed with the WM_MOVE message. The default message processing logic in DefWindowProc() 
will handle these messages if the program does not intercept them. 


Uses “Moving, resizing, or repainting a window. 
Retarns =—_—No returned value (void). 
See Also . ShowWindow(), GetClientRect(), GetWindowRect(), SetWindowSize() 
Parameters | 
hWnd HWND: A handle to the window. 
, a int: The new horizontal position of the window’s upper left corner. For parent and popup ¥ win- 


dows, X is in screen coordinates. For child windows, Xi is in client coordinates. 
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Y 


nWidth . 
nHeight — 
bRepaint 
Related Messages 
Example 


int: The new weticdl position of the window's upper left corner. For agent and popup windows, 
Y is in screen coordinates. For child windows, Y is in client coordinates. 


int: The new client area width. 

int: The new client area height. 

BOOL: Specifies if the window should be repainted. TRUE if yes, FALSE if not. 
WM_SIZE, WM_MOVE 


This program fragment shows a window being moved ten times, each time changing its size. Note 
how GetWindowRect() is used to determine the window’s initial size. 


tong FAR PASCAL WndProc CHWND hwnd, unsigned iNessage, WORD wParam, LONG (bere) 
{ =. obi 


static RECT rWindow ; 
static int iy 
switch (iMessage) /* process windows messages */ 
{ : 
case WM_COMMAND: : /* process menu items */ 
switch (wParam) : 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
GetWindowRect ChWnd, &rWindow) ;. 
for (i =0; 1<10; i++) 
{ 
MoveWindow (hWnd, rWindow.left + i*10, 
rWindow.top + i*10, 
rWindow.right + i*10, 
rWindow.bottom + i*10, TRUE) ; 
} 
break ; 
[Other program lines] 
REMOVEPROP ; Win2.0 mWin3.0 .mWin3.1 
Purpose Removes a property (data) that was associated with a window. 
Syntax HANDLE RemoveProp(HWND hWnd, LPSTR lpString); 
Description Frees the memory associated with the properties data. 
Uses _ Use when the property is no longer needed, or when shutting down an application (processing a 
WM_DESTROY message). ° 
Returns ~ Ahandle. The handle points to the property name if the function was successful. Otherwise, the 
function returns NULL. 
See Also SetProp(), GetProp(), EnumProp()_ 
Parameters 
hWnd HWND: A handle to the window which has property data. : 
lpString LPSTR: A pointer to the string that contains the property name. If atoms are used to name the 
property, the high-order word will be zero, and the low-order word will be equal to the atom’s 
value. 
Example This example uses a window property value to hold a handle for a global memory block containing 


a character string. The property is removed when the program terminates. Note that the memory 
block must be separately freed using GlobalFree().: 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG iparan) 
{ ‘ 


static 
. LPSTR. 
char 


HANDLE. hMemory ; 
lpName ; 
cBufC] = “This data tied to Window"; 
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switch (iMessage) /* process windows messages */-- 
{ i . 


case WM_CREATE: -. 
hMemory = GlobalAlloc CGMEM_MOVEABLE | GMEM_ __ZEROINIT, 
-CLONG) strlen (cBuf)) ; 
LpName = GlobalLock ChMemory) ; 
lstrcpy (lpName, cBuf) ; 
GlobalUnlock ChMemory) ; 
SetProp. sheng: “User Prop" , hMemory) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 

} 4 
break ; 

case WM_DESTROY:. '  /*® stop application */ 
GlobalFree (hMemory) ; 
RemoveProp (hWnd, “User Prop") ; 
PostQuitMessage (0) ; 


break ; 
default: oO /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
+. me . 
return COL) ; 
: 
SETACTIVEWINDOW : mWin20 mWin30 mWin3] 
Purpose Makes a window active. . 
Syntax HWND SetActiveWindow(HWND hWnd); 
Description - Sets the active window. The active window is the parent window with the input focus. The active 
window can be iconic. 
Uses Used in applications that coordinate the actions of several independent windows, See Chapter 30 
; on dynamic data exchange (DDE) for how to exchange data and commands between running 
applications. 
Returns HWND, a handle to the previously active window. » 
Comments This function should not normally be used, as it risks violating one of the basic principles of 
: Windows programing: letting the user determine which window should be active at any time. You 
may find it useful when a function key or key combination activates a window, a: as an alternative to 
mouse control. 
See Also GetActiveWindow(), GetLastActivePopup(), EnableWindow(), BringWindowToTop() 
Parameters | a 
hWnd HWND: A handle to the window to activate. 
Related Messages WM_ACTIVATE , 
Example This code example creates a window that refuses to be covered up. Ten seconds after the “Do It!” 


menu item is clicked, this program will come back to the top, even if it has been covered. by 
several other windows. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ “ 


switch poe one ee /* process windows messages */- 


case WM_TIMER: 
KillTimer Chund, 1); 
SetActiveWindow. chwnd) 7/* make window reappear */ 


87 


WINDOWS API BIBLE 


break; : . i 
. case WM_ COMMAND: _. .  /* process menu items */ 
switch (wParam) : ; 


case IDM_DOIT: 
-. /* set timer 1 to every 10 sec. */ 
if (!setTimer ChWnd, 1, 10000, NULL) > , 
a it ChWnd, "Too many clocks or timers!",- 
“Warning”, MB_ICONEXCLAMATION | MB_! OK) ; 


Pa a break ; 
[Other program lines] 
SerCassLonc — , “mm Win2.0) @Win3.0 Wind. 
Purpose Changes one of the LONG values in a waar class, . 
Syntax LONG SetClassLong(HWND hWnd, int nIndex, LONG dwNewLong); 
Uses _ Allows you to change tlie window procedure or menu for an existing class. This allows you to make 
. use of an old class, with a new window procedure or menu applied to all Supeecuent windows 
created from the class. 


Also allows you to set the values of extra four-byte data that was allocated as part of the class 
data when the class was registered. Room is made for these values as the chClsExtra element of 
the WNDCLASS data structure is passed to RegisterClass(). GetCiassLong() can be used to re- 


_ trieve the values set. 
Returns _ Returns the previous value held by the window class. 
_ See Also SetClassWord), GetClassLong(), GetClassWord(), RegisterClass, Sinton 
Parameters 
hWnd _. HWND: A handle to a window. 2 
nindex . int: The index of the value to change. This can be either of the values in Table 3-9. 


GCL. MENUNAME ia anew sure pointer to the menu name. 
GCL_WNDPROC. Seta new long pointer to the window function. 


Table 3- 3-9, eisai ) Flags. 


The GCL_ flags are defined as negative values in WINDOWS.H. To change edt ae dake in 
the class definition, use a positive byte offset for n/ndex. Zero for the first value, 4 for the second, : 


— ete. 
dwNewLong  _ LONG: The new four-byte data to insert into the class data. 
Notes - Using the GCL_WNDPROC index to set a new window message processing function is called “win- 


dow subclassing.” All windows created from the class after the window function is changed will 
use the new message processing function. 
Do not change the class settings for predefined child window controls, such as buttons and 
- scroll bars, as these global classes are used by other applications. Instead, change the values for 
the individual controls using SetWindowLong(). 


Example i. This program modifies the existing window class by changing the window. arvcodre: name. All 
‘subsequent calls to CreateWindow() create child windows referencing WindProc2(). Note that 
WindProc2 must be added. to the EXPORTS section of the program's .DEF definition file, and a. 

7 . function prototype must be added to the header file. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned imessage, WORD wParam, LONG (Param) 
: 


He DC ;. 


3 


} 
’ peturn (OL) ; 
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PAINTSTRUCT -  ==————saPS 


HWND ~hChild a 
switch Cimessage) an _ ¢* process windows messages */ 
t 


case WM_PAINT: 
hoc = BeginPaint ChWind, &PS) ; eA 
TextOut ChdC, 10, 10, "Now in Peiaeny WndProc.", 23) ; ‘ 


EndPaint Chuind, &PS) ; 
break ; 
case WA_. COMMAND: /* process menu items */ 
switch (wParam) 
{ co : : 
case IDM_DOIT: © /* create a child window — use sWindProc2() */ 


SetClassLong (hWnd, GCL_WNDPROC, (LONG) WndProc2) ; 
hChild = CreateWindow (gszAppName, "Child Window", 
WS_CHILD | WS_VISIBLE | WS BORDER | WS_CAPTION, 
100, 50, 200, 150, hind, NULL, ghinstance, NULL) ; 
: ShowWindow (hehild, SW_SHOW) ; 
‘ break ; 
case IDM_QUIT: 
bedded Ale ha Chiind) 7 


break ; 
} . 
break ; 
case WM_DESTROY: . /* stop application */ 
PostQuitMessage (0) ; 
break ; ‘i ra 
default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, (Param) ; 


/* This is the new WindProc() referenced by the SetClassLong() function. */ 

/* ALL new children created use this one. */ 

long FAR PASCAL WndProce cng hwnd, unsigned. iMessage, WORD wParam, LONG \param) 
{ 


HDC : hDC ; 
PAINTSTRUCT PS ; 


switch (iMessage) . = /* process windows messages x/ 


case WM_PAINT: 
hOC = BeginPaint (hWnd, &PS) ; 
TextOut C(hOC, 10, 10, om in SECOND WndProc.", 22) > 
endreint Chuind, GPS) ; 


break ; ; 
case WM _ DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; . 
default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, \Param) ; 


} 
return (OL) ; 


SerCassWorp — | se Win2.0 sw Win3.0 Wind.) 
Purpose . ~ Changes a WORD sized value ina eit class. ar 
‘Syntax __ .WORD SetClassWord(HWND hWnd, int nIndex, WORD wNewWord), 

Description =—s_ This function allows you to change the properties of every window created from an existing chess, 
a ne a - It is often used to change the cursor shape, but can also be used to oe any of the extra two- 
ae = byte wide data stored with the. window class structure. : 


| eoaree See trclone Sal, ata ahah e 
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See Also” . 
Parameters — 
hWnd - 


ox ‘SetClassLong0) GetclaseWord0), GetClassLong() 


HWND: Handle to the window that was created based on the class. 
int: The byte offset for the specific. data item. It can be any of the values in Table 3-10. 


GOW. OBOLSECRA Retrieve the number of bytes of extra data associated with the class. A second call to. 


‘ GetClassWord() can be used to retrieve a word of data. Use an nindex value of 0, 2, 4... for the 
first, second, third... words of extra data. 


GCW_CBWNDEXTRA Retrieve the number of bytes of extra data associated with the window. A second call to 


GetClassWord{) can be used to retrieve a word of data. Use an nindex value of 0, 2, 4... for the 
first, second, third... words of extra data. 


GCW_HBRBACKGROUND _Retrieve a handle to the class background brush. 


GCW_HCURSOR 
GCW_HICON 
GCW_HMODULE 
GCW_STYLE 


Retrieve a handle to the class cursor. 
Retrieve a handle to the class icon. 
Retrieve a handle to the class module. 

_ Retrieve a handle to the window class style. 


sane 3-10. SetClassWord( ; Flags. 


wNewWord 
Note 


Example 


bee \ 
The GCW_ flags are defined as negative values in WINDOWS.H. To change extra word-sized data 
associated with the window, use a positive offset es nIndex. Zero for the first byte, 2 for the 
second, etc. 


WORD: The new word-sized value to insert into the class structure. 


Do not change the class settings for predefined child window controls such as buttons and scroll 
bars, as these global classes are used by other applications. Instead, change the values for the 
individual controls using SetWindowWord(). 


Here the “Do It!” menu item causes the window’s class to be altered to a light gray baclerouikd: 
This affects all of the child windows created and also affects the parent window's client area on 
the next refresh (WM_PAINT) cycle. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) ne 
{ . 3 3 


HWND hChild ; 
switch (imessage) | /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 2 
oa IDM_DOIT: (  /* User hit the “Do it" menu item on 


SetClassWord (hWnd, GCW_HBRBACKGROUND, 
CWORD) GetStockObject (LTGRAY_BRUSH)) ;. 

" hChild = CreateWindow (gszAppName, "Child Window", 
WS_CHILD | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
100, 50, 200, 150, pwnd 9: NULL, ghinstances, NULL) ; 

ShowWindow ChChild, SW_SHOW) ; 

break ; 


case IDM QUIT: 
; DestroyWindow (hWnd) ; 
break ; 
}. 
break ; 


case we DESTROY: .. iA stop application */ 7° | 


~ 90 


- °3" WINDOWS SUPPORT FUNCTIONS ¥ 


Postaui tNessage (0) ; 


break ; 
default: , /* default windows message processing, */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} st 
return (OL) ; 
} + 
SetFocus. 7 gWin.0 we Win8.0 Win 31 
_ Purpose Gives a window the input focus. * 
Syntax = . HWND SetFocus(HWND hWnd); 
Description : A window with the input focus gets all of the keyboard input. 
_ Uses Frequently used where there are multiple child windows. Controls which one has the input focus. 
Returns . .A handle to the window that previously had the input roe. NULL if hWnd is not a valid window 
. . handle, or if the window is disabled. . = 
See Also GetFocus(), EnableWindow() 7 
Parameters 
hWnd HWND: A handle to the window which i is to receive the input focus. 
Related Messages WM_ SETFOCUS, WM_GETFOCUS 
Example Here the “Do It!” menu item causes the keyboard input focus to be moved to the edit control. This 


shows up in the changed appearance of the edit line in the edit box. The text in the edit control 
goes from gray to black, and an edit cursor appears inside the control. This is the same effect that 
clicking the edit control with the mouse would have. 


Long FAR PASCAL ‘WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 2 


static. .HWND hEdit ; 
' static BOOL ; bFirstTime = TRUE ; 
switch CiMessage) re . /® process windows messages */ 
Co ‘ 4 
case WM_CREATE: __/* create and show an edit control */ 
if (bFirstTime) 
{t 


hEdit = CreateWindow ("EDIT", “Edit Me", 
WS_CHILD | WS _VISIBLE | WS_BORDER, 
150, 40, 100, 25, hwnd, NULL, ghInstance, NULL) ; 
ShowWindow (hEdit, SW_ SHOW) ; 
bFirstTime = FALSE ; 
} 
break ; : 
case WM_COMMAND: x /* process menu items */ - 
switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 


SetFocus ChEdit) ; 
break ; 
[Other program lines] 
SeETPARENT : wWin2.0 mWin3.0 mw Win3.1 
Purpose Changes the parent window of a child window. . 
Syntax HWND SetParent(HWND hWndChild, HWND hWndNewParent); 
Uses Child windows can be children of child windows, to any desired level of nesting. The advantage is 
_ that child windows do not exceed the bounds of their parent’s client area and are moved with the 
parent. 
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Returns HWND, a handle to the previous parent window of hWndChild. 


See Also GetParent(), GetextyndenO, Mn) 
hWndChild HWND: A handle to the child sindee: which is to receive.a new par- 
ent. 7 
hWndNewParent HWND: A handle to the new parent window of hWndChild. 
Example §-—=_=sIn this example, two child windows are created. Initially, they overlap Figure 3-15. Child 


each other on the screen, as both have the same parent window.When Windows Afler :  _ 
the user clicks the “Do It!” menu item, the second child window be- _ Clicking “Do It!”. . 

’ comes the child of the first child window, forcing child2 to be visible 

only within the client area of child). Note that these child windows share the message processing 
function WndProc() of their parent, as they are based on the parent’s class. Real child windows 
would have their own message processing functions. (See Figure 3-15.) 


long FAR PASCAL WndProc (CHWND hwnd, unsigned iNessage, WORD wParam, LONG (Param) 
{ 


static HWND hchildt, hChilde ; 
Static. BOOL bFirstTime = TRUE ; 


switch (iMessage) a ee Mal process windows messages 77 
case WM_ CREATE: > ae build ane child window. when program starts */ 
if (bFirstTime) 
g 


bFirstTime : = FALSE He 
AChild4 = CreateWindow (gszAppName, "Child Winaew: a Faas 
WS_CHILD | WS_VISIBLE | WS_BORDER | WS-_ CAPTION, | 
10, 50, 300, 250, hWnd, NULL, ghInstance, ULE 
’ ShowWindow Chchildt, SW_SHOW) ; 
- hWChild2 = CreateWindow (gszAppName, “Child Window 2", 
WS_CHILD | WS_VISIBLE | WS_BORDER | WS CAPTION, — 
ae 10, 50, 200, 150, hwnd, , NULL, ehtnstence, NULL) ; 
ShowWindow (hchild2, SW_. SHOW) ¢ 


}. 
‘break ; ie 
case WM_COMMAND: =~ /* process menu items */ 
- switch (wParam) . 
: tie. At . 
case IDM_| DoIT: ‘" 7* User hit the “Do it" menu item */ 
SetParent Chchild2, hChild1) ; 
f break ; 
. [Other program lines] 
SeTProp : e — | mWin20 _aWin30 mWin3l 
Purpose Attaches named data toa window. | oe es ete 
Syntax BOOL SetProp(HWND hWnd, LPSTR lpString, HANDLE abate); ae 
Description SetProp() allows any data to be associated with the window hWnd. The data is given a name, “S 
pointed to by ipString, to make recall simple. Normally hData i is a handle to a memory block — 
: containing the actual data. hData canbea 16-bit value. ~ 
Uses An excellent way to keep track of data that is specific to a even window. Avoids the use of gobal 
variables in many cases. 
Returns __ BOOL. TRUE if the data was added to the window's property list, ee if not. 
 SeeAlso GetProp(), Releanalion() EnumProp() 
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Parameters 

hWnd HWND: A handle to the window which is to receive the property data. 

lpString LPSTR: A pointer to a string containing the. name to be used for the data. This can also be an 

atom. In that case the high-order word of /pString should be zero, While the low-order word 
contains the atom’s 16-bit value. 

hData HANDLE: A 16-bit value. Normally a handle toa memory block allocated with either Hocalilioel) 
or GlobalAlloc(). . 

Example See the example under the GetProp() function description Ms: 

SerSysMopaLWinpow : 3 m@Win2.0 mWin30 mWin31: 

_ Purpose Makes a window system-modal. 
Syntax HWND SetSysModalWindow(HWND hWnd); 

Description = System-modal windows take over the screen, so only they can have the input focus. A typical 
example is the final message from Windows’ program manager, which confirms that the user 
wants to exit Windows. If a system-modal window creates another system-modal child window, 
the new window takes over the system. Control returns to the first system-modal window after 

the second one is destroyed. 

Uses For critical messages and responses to/from t the user. This function is seldom called directly, as 

normally system-modal windows are created as dialog boxes. The window style DS_ SYSMODAL 
automatically creates a system-modal dialog box, euininatine S the need to ot SetSysModal- 
. Window(). 

Returns HWND, a handle to the previous system-modal window (if any). 

See Also - GetSysModalWindow() 

Parameters 

‘AWnd HWND: A handle to the window which is to become system-modal. 

Example In this example, the focus can be switched back and forth between the parent and: client window 


until the “Do It!” menu item is clicked.’ After that, the popup window becomes a system-modal 


_ window and will not give up the focus. Hitting a key deletes the window, and stops the program. 


tong FAR PASCAL WndProc CHWND hwnd, unsigned iMesgage, WORD wParam, LONG: ‘UParam) 
€ 


HOC hoc ; . /* device context handle “/ 
static WNOCLASS ' wndclass ;. /* the window class */ 
static HWND hPopup, hParent ; 

switch CiMessage) : : /* process windows messages */ 

{ 


case WM_CREATE: /* build the child window when program starts Lat A 
wndclass.style 
= CS_HREDRAW | CS_VREDRAW. i cs SEARS NTC! 2 
wndclass. lpfnwWndProc = ChildProc ; 


wndclass.cbClsExtra ‘ 


wndclass.cbWndExtra =0; \ 

wndclass.hInstance = ahtnataacess 

wndclass.hIcon : = NULL ; 

wndctass.hCursor = LoadCursor (NULL, IDC_ARROW) ; 
vridclass. hbrBackground = GetStockobject CLTGRAY_| BRUSH) ; 

wndclass.lpszMenuName = NULL ; 

wndclass.lpszClassName = “SecondClass" 5 : 


/* register the window class */ 
if(RegisterClass (&wndclass))- 
{ 


hPopup = CreateWindow ("SecondClass", “Popup Window", 


a: ae 


WINDOWS API BIBLE 


WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
-10, 50, 200, 150, hind, NULL, ghInstance, NULL) ; 
se “ ShowWindow (hPopup, SW_ SHOW) ; 
‘3 
break ; on ; an 
case WM_ COMMAND :. '-../* process menu items */ 
switch (wParam) 2% 


‘case IDM_DOIT: /* User hit the "Do it" menu item */ 
- SetSysModatwindon ChPopup) ; 


break ; 
case IDM_QUIT: . /* send ‘end of application s message nes 
\. : Destroywindow (hWnd); 
> break ; 
“):. 
break ; ¥ 
case WM_DESTROY: a hd stop application ef 
PostQuitMessage (0) ; : 
break ; 
default: | y+ default windows message processing *f 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} : ; 
return COL) ; 
>. ! 


/* Here is'a separate message processing procedure for the popup window */ 
long FAR PASCAL ChildProc (HWND hWnd, unsigned iMessage, WORD wParam, 
LONG Phare: 


Cs ne 
HDC ; hDC ; 
PAINTSTRUCT PS ; 
switch (iMessage) : /* process windows messages */ 
C S aNisy 2 : in 9 
case WM_PAINT: | 
hDC = BeginPaint wads RPS) ; 
TextOut (hDC, 5, 5, snus a key: 10) ; 
EndPaint ChWnd, BPS) ; 
break ; 
case WM_| KEY DOWN: : ; 
case WM_DESTROY: /* stop the application Le 
‘ POSE Aus Message: (0) ; 
break ; a: 
default: ye default windows message processing at 
return DefWindowPrac (hWnd, iMessage, wParam, lParam) -; 
return (OL) ; 
SetTWInDOWLONG - ll ue 2.0. mWin3.0 . mWin3l 
Purpose Changes a LONG value associated with a window. 
- Syntax LONG SetWindowLong(HWND hWnd, int nIndex, LONG dwNewLong); 
_ Description Used to change the style. f a window, or to change the window's message processing function. 


Can also set extra 16-bit data stored with the window if the window’s class definition includes 
space as the chbWndExtra flement of the WNDCLASS data structure passed to RegisterClass(). 


‘ Uses... .... Most oftenused to do window subclassing. It allows you to add to, or replace the existing window's. 

“>. «message processing logic by passing a new window message function to the specific window or 

~~ control. Also used to associate extra data with the window. It can be-used in place of setting 
- window property data, if the amount of data stored with each window is small. 


7 Retarns 5 . The previous LONG value. | 
_ | See Also Setindow Word), GetWindowLong0, GetWindowWordQ 
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Parameters 
hWnd HWND: A handle to the window. 
nIndex int: An integer offset, determining which value is to be changed. This can be any of the values i in 


Table 3-11. 


GWL_! EXSTYLE Sets anew enna window sce See 2 CreateWindowEx) in Giedier 2; cena Windows, a a ist of ne 
GWL_STYLE Sets a new window style. See CreateWindow() in Chapter 2 for a list of styles. 
GWL_WNDPROC Sets a new long pointer to the window procedure. \ 


Table 3-11. SetWindowLong( ) Flags. 


The GWL_ values are defined as negative values in WINDOWS. H. To access any extra four- 
byte data defined in the window’s class structure, use a positive n/ndex value. Zero for the first 
value, four for the second, etc. 


dwNewLong = DWORD: The new 32-bit value. 


Problems. . —‘ Take care not to include functions in the new message processing function that cause Windows to 
fe - call the function again. This sets up an infinite loop and overflows the stack. For example, adding 
the GetScrollPos() function into NewScrollPos() shown below will fail, as GetScrollPos() ends up 

forcing another call to the subclassed NewScrollPos() function. 


Example In this example, a scroll bar is placed at the bottom of the window’s client area. After clicking the 
“Do It!” menu item, the scroll bar has the input focus. The scroll bar window is subclassed, provid- 
ing additional message processing logic from the NewScrollPos() function listed at the bottom. 
The scroll bar thumb responds to both the left and right arrow keys and the page-up and page- 
down keys. Note that the NewScrollPos() function must be added to the EXPORTS section of the 

' program’s .DEF definition file. A function prototype must also be added to the program’ S header. 


file. 2 ; 
FARPROC ipfnOldScroltProc ; “<4 /* static to hold old proc polater # 
int nScrollPos ; ie? o /* static to hold thumb position */ 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG tParam) | 
{ fa . f. os 


static HWND hScroll ; . 
FARPROC LpfnNewScroltProc : 


HDC . HDC ; 
RECT rClient 3 
switch CiMessage) /* process windows messages */ 


case WM_CREATE: 


GetClientRect (hWnd, &rClient) ; 

hScroll = CreateWindow CSCROLLBAR", ear = 
WS_CHILD | WS_VISIBLE | SBS_! “BOTTOMALIGN | SBS. HoR?, 
rClient.left, rClient.top, rClient.right, 

rClient.bottom, hWnd, NULL, ghinstance, NULL) ; 

ShowWindow (hScroll, SW_: SHOW) ; : 

SetScrollRange ChScroll, SB CTL, 0, 9, FALSE) ; 

SetScrollPos ChScroll, SB CTL, O, TRUE) ; 

nScrollPos = 0 ; 


/* subclass the scroll bar toa new 1 procedure ey 
LpfnNewScroltProc = MakeProcinstance 


CCFARPROC) NewScrollProc, ghInstance) ; 
lpfn0ldScrollProc = CFARPROC) GetWindowLong ChSeroll, 
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GWL_WNDPROC) ; 
Ne ““SetWindowLong chSerolt, GWL., —WNDPROC, 
“ee ; CLONG) EpANHSMSCrOLCPROE2 v2 ; woke 
break ; ; \ 
case WM_| SETFOCUS: 
SetFocus ChScroll) ; 
2 break ; an 
case WM_COMMAND: /* process menu items */ 
. switch (wParam) - . : ae 
ie ae 
case IDM_DOIT: — /* User hit the “Do it” menu item */ 
ADC = GetDC ChWnd) ; 
TextOut (hdc, 10, 10, 
"Try left/right arrow and pg up/dn.", 34) ; 
‘ ReleasedC (hWnd, hoc) ; a 
SetFocus (hScroll) ; 
break ; -4 
case IDM_QUIT: /* send end of application message. */ 
— DestroyWindow ChWnd) 5 
_ break ; w - 
mee 
' break ; 
case WA _ DESTROY: /* stop application */ 
Postauithessage (0) ; 
; break ; 
default: , /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


>. 
eeturn (OL) ; 
>. * 


Long FAR PASCAL, NewScrollProc CHWND hWnd, WORD mess, WORD wParam, LONG LParam) 
: | int nOldScrollPos ; | 
nOldScrollPos = nScroltPos ; 
suites (mess) 


case WH_KEYDOWN: 
switch (wParam) 


case VK_RIGHT: /* process left and right arrow keys */ 


case VK_NEXT: : ' “/* and page-up, page-down keys */ 
_ MScrollPos++ 5° 4 
break ; 


case VK_LEFT: 

case VK_PRIOR: 

nScrollPos-- 
break ; 


Re 


} 
if (nOldScrollPos != nScrollPos) : 
SetScrollPos (hind, SB_CTL, nScrollPos, TRUE) ; 


} 

return CallWindowProc (lpfn0ldScroilProc, hWnd, mess, wParam, (Param) ; 
>) | . 
SerWinpowPos oo os! — | aWin20 gWin30 mWin3l 
Purpose Simultaneously changes the size, sana and ordering of windows. 
Syntax void SetWindowPos(HWND hWnd, HWND hWndInsertAfter, int X, int Y, int cx, int ws WORD 


. wFlags); — 
Description . Windows are ordered in Windows’ internal list based on their appearance on the screen. The 
4 window on top of all the others is the highest ranked. This function changes that oeerint allow- 
a. ang ute Bag anton to te tp 


Uses 


Returns 
See Also 


Parameters 
hWnd 


hWndInsertAfler 
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Used with applications that have multiple child and popup windows that can become obscured. 
Use GetTopWindow() to find the current top window. 


No returned value (void). 
GetTopWindow(), MoveWindow() 


HWND: A handle to the window that will be affected. . 


HWND: The handle of the window after which the hWnd window is to be inserted. Can be set to 
NULL, which places hWnd at the top-most position. Set to one to place hWnd above all top-most 
windows, even when deactivated. 

int: The new horizontal position of the hWnd's top left corner. For child windows this is in client. 
coordinates. For popup windows, this is in screen coordinates. Can be zero if the SWP_NOMOVE 


value is used for wFlags, meaning no change to the window’s position after reordering. 


int: The new vertical position of the hWna’s top left corner. For child windows, this is in client 
coordinates. For popup windows, this is in screen coordinates. Can be zero if the SWP_NOMOVE 
value is used for wFlags, meaning no change to the window's position after reordering. 

int: The new width of the AWnd window. Can be zero if the SWP_NOSIZE value is used for wFlags, 
meaning no change in the window's size after reordering. 

int: The new height of the hWnd window. Can be zero if the SWP_NOSIZE value is used for wFlags, 
meaning no change in the window’s size after reordering. 

WORD: Can be any combination of the flags shown in Table 3-12, combined using the C language 
binary OR operator (1). 


SWP_ DRAWFRAME 


SWP_HIDEWINDOW 


SWP_NOACTIVE 
SWP_NOMOVE 


SWP_NOSIZE 


SWP_NOREDRAW 


SWP_NOZORDER 


SWP_SHOWWINDOW 


Draw the window's frame when rain The frame “hye is defi peal in the window's class defi- 
nition. See RegisterClass(). 


Hide the window after reordering. 
Do not make the window active after reordering. 


Do not charge the position of the window after reordering. The X and ee are ignored if 
this flag is used. 


Do not change the size of the window after reordering. The cx and cy parameters are ignored if 
this flag is used. 


Do not redraw the window after reordering. 


Do not change the window's order in the window list. This makes SetWindowPos() equivalent to . 
MoveWindow\). 7 . F / 


Redraw the window after reordering. 


Table 3-12. SetWindowPos() Flags. 


Related Messages WM_SIZE, WM_MOVE, WM_PAINT 


Example 


Two popup windows are created in the following WndProc() fragment. If the user 1 clicks the “Do 
It!” menu item, the first child window is positioned above the second. Because of the three SWP_ 


- parameters used in SetWindowPosition(), the-size and location of the window is not affected. 


This is why the four size parameters are set to zero. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


’ 
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HOC . hDC ; 
static HWND hChild1, hChild2 ; 
char cBuf [25] ; 
static BOOL bFirstTime = TRUE ; 
BOOL bIsVisible ; 
switch (iMessage) /* process windows messages */ 
‘ case WM_CREATE: ‘/* build the child window when program starts */ 
if (bFirstTime) 
{ 
bFirstTime = FALSE ; 
hChild1 = CreateWindow (gszAppName, "Child Window 1", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 10, 300, 250, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hChild2, SW_SHOW) ; * 
hChild2 = CreateWindow (gszAppName, "Child Window 2", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
20, 20, 200, 150, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hChild2, SW_SHOW) ; 
3 
break ; ’ 
case WM_COMMAND: /* process menu items */ 
switch (wParam)” 
{ . 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
SetWindowPos (hChild1, hcChild2, 0, 0, 0, 0, 
SWP_NOSIZE | SWP_ DRAWFRAME | SWP __NOMOVE) ; 
break ; 
[Other program lines] 
SerWinpowText BWin20 e8Win30 gWin3] 
Purpose Changes the caption (title) of a window. 
Syntax void SetWindowText(HWND hWnd, LPSTR lpString); 
Description For windows with a title bar, the title shows up in the center of the caption area. For buttons, the 
- title is inside of the button. 
Uses. Changes a window’s title. Note that the title string is displayed at the bottom of the window icon 


when the window is minimized. You can use this function to shorten the title when the window is 
minimized so that the title string fits under the icon, rather than running into other icons’ titles. 


Returns No returned value (void). 

See Also GetWindowText() | 

Parameters 

hWnd HWND: A handle to the window. © 

LpString LPSTR: A pointer to a null-terminated string containing the new title. Windows will truncate the 
title if it does not fit within the title area of hWnd. 

Example This example changes the caption of the} main window when the user clicks the “Do It!” menu 
item. 


ra FAR PASCAL WndProc CHWND nend, unsrgned iMessage, WORD BPaCee? LONG lParam) 
switch CiMessage) , |* process windows messages */ 
t 


case WM_COMMAND: : ep process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item ee 
SetWindowText (hWnd, "I'm the new title!) ; 
break ; 


[Other program lines} 
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SETWINDOowWorD | sg Win2.0) sm Win3.0) mm Win3.! 
Purpose Changes a WORD value associated with a window's class structure. , 
Syntax WORD SetWindowWord(HWND hWnd, int nIndex, WORD wNewWord); 


Uses Normally used to change the control ID of a child window control. Can also be used to set 16-bit 
data associated with the window. This assumes that room for the data provided by the 
cbWndExtra element of the WNDCLASS data structure was set large enough to hold the data 
when the class was registered with RegisterClass(). 


Returns WORD, the previous value. 

See Also GetWindowWord(), SetWindowLong(), GetWindowLong() 
Parameters é | 

hWnd | HWND: A handle to the window. 


nindex int: An index to the value to be changed. This can be either of the values in Table 3-13. 


Change the instance handie of the module that owns the window. 
GWW_ID Change the control !D of a child window control. 
Table 3-13. SetWindowWord() Flags. 


The GWww_ values are defined as negative integers in WINDOWS.H. To change extra WORD sized 
data defined in the window's class structure, use a positive 2/ndex offset. Zero for the first value, 
2 for the second, etc. 
wNewWord WORD: The new 16-bit value. 
Example The button control's ID value is changed to 1000 when the user clicks the “Do It!” menu item. 


iong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


static HWND hButton ; 
HDC hdc ¢ 
int nID; 
char cBuf C25] ; 
switch CiMessage) /* process windows messages */ 
{ e 
case WM_CREATE: ' /* initially created with ID = 99 */ 


hButton = CreateWindow ("BUTTON", "Button", 
WS_ CHILD | WS_VISIBLE | BS_PUSHBUTTON, 
' 10, 10, 100, 40, hWnd, 99, ghInstance, NULL) ; 
ShowWindow ChButton, SW_SHOW) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menuitem */ 
hDC = GetDC ChWnd) ; a 
TextOut (hoc, 10, 60, "The button's ID was:", 20) ; 
nID = GetWindowWord ChButton, GWW_ID) ; 
itoa (nID, cBuf, 10) ; 
TextOut ChDC, 10, 80, cBuf, strlen (cBuf)) ; 
TextOut ChDC, 10, 100, “The new ID is:", 14) ; 
SetWindowWord ChButton, GWW_ID, 1000) ; 
nID.= GetWindowWord (hButton, CWWLID) ; . 
itoa (n1D, cBuf, 10) ; 
TextOut (hoOC, 10, 120, cBuf, strlen (cBuf)) ; 
ReleaseDdC (hwnd, hDC) ; 
break ; 


[Other program lines] 


' 99 
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SHowOwnepPopurs | | Win2.0 wWin30 mWin3.1 

Purpose ‘Shows or hides all popup windows associated with the parent window. 

Syntax void ShowOwnedPopups(HWND hWnd, BOOL bShow); 

Uses Allows a “one shot” update of all the popup windows, without needing to individually call _ 
a . ShowWindow() for each one. 

Returns  =—Ss-—s No returned value (void). 

See Also ShowWindow() 

Perameters Ba . . 

hWnd HWND: A handle to the parent window which may own popups. 

bShow BOOL: TRUE to show all owned popup windows, FALSE to hide all of them 

Related Messages WM_SHOWWINDOW 

Example = ———swHere the two popup windows created vanish and reappear when the user repeatedly clicks the 


“Do It!” menu item.. . 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) ; 
r¢ . 


‘ static HWND hChitldt, hChild2 ; 
static BOOL bFirstTime = TRUE ; 
static BOOL bPopupsShowing = TRUE ; 


switch (iMessage) thal process windows messages */ 
case WM_. CREATE: 7 '/* build the child window when program starts */ 
if ¢ FirstTime) . 
t 


 bFirstTime = FALSE ; 

hChild1 = CreateWindow (gisisalaae; “Popup Window 1", 

. WS_POPUP | WS_VISIBLE | WS_BORDER | WS _CAPTION, 
10, 10, 300, 250, hind, NULL, ghInstance, NULL) ; 

ShowWindow (hChild2, SW_SHOW) ; 

hChild2 = CreateWindow CaszAppName, "Popup Window 2”, 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_!' CAPTION, 
20, 20, 200, 150, hWnd, NULL, ghInstance, NULL) ; 

ShowWindow (ChChild2, SW_SHOW) ; 


?. 
break ; a 
case WM_COMMAND: /* process menu items */ 
switch (wParam) ° 
c 
case IDM_DOIT: : /* User hit the "Do it” menu item */ 
: tf (bPopupsShowing) 
{ 
bPopupsShowi ng = FALSE ; 
ShowOwnedPopups ChWnd, FALSE) ; 
“yy. : ; 
else : 
Paes, 6 
bPopupsShowing = TRUE ; 
ShowOwnedPopups (hWnd, TRUE) ; 
a 
. break 
[Other program lines]. . 
SHowWinnpow = ss ies eWin2.0 wWin30 w8Win3] 
Purpose Displays, hides, or changes the size of a window. ; 
Syntax _ BOOL ShowWindow(HWND hWnd, int nCmdShow); 
Description sree neon Od is normally called right after a window 1s created to omake it visible. 


meee 
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Uses Minimizing and maximizing the window, as well as making the window visible. Note that calling 
ShowWindow() does not guarantee that the window will not be obscured by other windows on the 
screen. Use SetActiveWindow() or SetWindowPos() to bring windows to the top. 


Returns . BOOL. TRUE if the window was visible, FALSE if the window was hidden. 

See Also CreateWindow(), SetActiveWindow(), SetWindowPos() 

Parameters ° 

hWnd HWN: The handle to the window. 

nCmdShow int: An integer value specifying the action to 02 taken. It can be any one of the values in Table 3- - 


14 (not a combination). 


SW HIDE Hides the Win: The top window on Window’ S list is ae 

SW_MINIMIZE Minimizes the window. The top window on Window's list is activated. 

SW_RESTORE , Activates and displays the window (same as SW_SHOWNORMAL). 

SW_SHOW . Activates and displays the window in its current size and position. 

SW_SHOWMAXIMIZED Activates and maximizes the window. 

SW_SHOWMINIMIZED Activates and minimizes the window to an icon. 

SW_SHOWMINNOACTIVE Displays and minimizes the window. The currently active window remains active. 

SW_SHOWNA Displays the window, tut does not change which window is active. 

SW_SHOWNOACTIVE Displays the window, but does-not change which window is active. Bo 
SW_SHOWNORMAL Activates and displays the window. If the window was minimized or maximized, the window i is 


returned to its previous size and position. 
Table 3-14. ShowWindou( ) Flags. 


Related Messages WM _SHOWWINDOW 

Example This example hides a child window when the user clicks the “Do It!” menu item. 
- long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage; WORD wParam, LONG lParam) 

{ 


HDC hoc ; 
static HWND hChild ; 
char cBuf C25) ; 
static BOOL bFirstTime = TRUE ; 
BOOL bIsVisible ; 
switch (iMessage) /* process windows messages */ 
{ 
3 case WM_CREATE: /* build the child window when program starts */ 
if (bFirstTime) 
{ 
bFirstTime-.= FALSE ; 
hChild = Createdindow (gszAppName, “Child Window", 
WS_CHILD | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
100, 50, 200, 150, hwnd, NULL, ghinstance, MULL? 23 
ShowWindow chenild, SW_SHOW) ; 
} 
break ; os 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ ; 
case IDM_DOIT: i* User hit the "po it” menu item */ 


hOC = GetDC Chwnd) ; 
bIsVisible = IsWindowVisible chehitd) ; 
if (bIsVisible) 
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{ ‘ 
GetWindowText (hChild, cBuf, 24) ; 
TextOut (hDC, 10, 20, cBuf, strlen (cBuf)) ; 
TextOut ChDC, 10, 40, “is now visible.", 15) ; 
TextOut (hDC, 10, 60, “Now hiding Child...", 19) ; 
: ShowWindow (hChi'd, SW_HIDE) ; ; 
} : sp 
else 


TextOut (hDC, 1020, 
“Child window not visible.", 25) ; 
ReleaseDC ChWnd, hDC) ; 


; ve break ; 
_ [Other program lines} 
SysTEMPARAMETERSINFO | | OWin2.0 OWin30 Wind 
Purpose Determines and/or change ssystem wide parameters. 
Syntax BOOL SystemParametersInfo (WORD wAction, WORD wParam, LPVOID lpvParam, WORD 
SWinInt); . 
Description This function allows a wide range of system parameters that control the way applications look 
and behave to be checked and changed. The changes can optionally be written to the WIN.INI 
file, making the changes effective in subsequent Windows sessions. 
‘Uses Used in replacing the Windows Control Panel program. 
Returns BOOL. TRUE if successful, FALSE on error. 
See Also GetSystemMetrics(), WriteProfileStringQ) 
Parameters _ 
wAction WORD: Any of the following values. The wParam and lpvParam values are used differently for 


each value of wAction, so their meanings are listed together. 


SPI_GETBEEP 


Determine if the warning beeper is on or off. 


wParam Set to 0. 

lovParam A pointer to a BOOL variable that will receive TRUE if the acca is on, FALSE Hf the beeper is 
off. 

SPI_GETBORDER Determine the width of window. sizing borders. 

wParam Set to 0. . 

ovParam A oointer to an integer that will receive the border multiplying factor. 

SPI_GETGRIDGRANULARITY Determine the spacing between items placed on the Windows desktop. 

wParam Set to 0. . 

iE aan A pointer to an integer that will receive the current spacing (granularity) factor. 


SPI_GETICONTITLELOGFONT —_Retrieve the logical font data for icon title. 


wParam Set to the sizeof) a LOGFONT structure. 
lovParam A pointer to a LOGFONT structure that will be filled in when the function returns. See the 
CreateFontindirect() function description for a description of the LOGFONT data structure. 
SPILGETICONTITLEWRAP Determine if icon title wrapping is set on or off. 
wParam Set to 0.. 
IpvParam A pointer to a BOOL variable that will receive TRUE if title wrapping is on, FALSE if title wrap- 
ping is off. 


102. 


SPI_GETKEYBOARDDELAY 


wParam 
IpvParam 


SPI_GETKEYBOARDSPEED 


wParam 
IovParam 


SPILGETMENUDROPALIGNMENT 


wParam 
IpvParam 


SPI_GETMOUSE 


wParam 
lovParam 


SPI_LGETSCREENSAVEACTIVE 


wParam 
lovParam 


SPI_GETSCREENSAVETIMEOUT 


wParam 
IpvParam 


SPI_ICONHORIZONTALSPACING 


wParam 
lovParam 


SPI_ICONVERTICALSPACING 


wParam 
 IpvParam 
SPI_LANGDRIYER 
wParam 
IpvParam 
SPI_SETBEEP 
wParam 
lpvParam 
SPI_SETBORDER 
wParam 
IpvParam 
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Determine the current keyboard repeat speed. 
Set to 0. 
A pointer to an integer that will receive the current keyboard repeat-delay. 


Determine the current keyboard auto-repeat speed. 

Set to 0. . 

A pointer to an integer that will receive the current keyboard auto-repeat speed. 

Determine if popup menus appear left-aligned or right-aligned relative to the top menu-bar 
item. 

Set to 0: 

A pointer to a BOOL variable that will receive TRUE if popup menus are right-aligned, FALSE 
if popup menus are left-aligned. 

Determine the mouse speed and the X and Y mouse threshold values. Movements smaller 
than the threshold do not result in mouse activity. 

Set to 0. 


A pointer to a three integer array (int value[3]) where: 
value[0] = X direction mouse threshold; 

value{1] = Y direction mouse threshold; 

value[2] = The mouse speed value. 


Determine if screen saving is on or off. 
Set to 0. 


A pointer to a BOOL variable that will receive TRUE if screen saving is on, FALSE if screen 
saving is off. 


\ 


Determine the screen save time period. 
Set to 0. 
A pointer to an integer that will receive the current screen save delay in seconds. 


Changes the horizontal icon spacing. 
Set to the horizontal icon spacing in pixels. 
Set to NULL. 


_ Changes the vertical icon spacing. 


Set to the vertical icon spacing in pixels. 
Set to NULL. 


Determine the language driver. 
Set to 0. 
A pointer to a character buffer that will contain the language driver file name. 


Turn the system beeper on or off. 
Set to TRUE to turn the beeper on, FALSE to turn the beeper off. 
Set to NULL. 


Change the window sizing border width. 
Set to the new border multiplier factor. 
Set to NULL. 
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Table 3-15. cuales 


SPI SETDESKPATTERN 


wParam 
IpvParam 


SPI_SETDESKWALLPAPER - 
wParam 
lovParam 


SPI_SETDOUBLECLKHEIGHT 


wParam 


. 


IpvParam 
SPI_SETDOUBLECLICKTIME 


wParam 
fovParam 


SPI_SETDOUBLECLKWIDTH 


wParam 
fovParam 
SPI_SETGRIDGRANULARITY 
wParam 
IpvParam 
SPI_SETICONTITLEWRAP 
wParam 
lpvParam 
SPI_SETKEYBOARDDELAY . 
wParam 
~ JovParam- | 
SPi_SETKEYBOARDSPEED 
wParam 
lovParam 


SPI_SETMENUDROPALIGNMENT 


wParam 
lpvParam 


SPI_SETMOUSE 


Sets the eds badgoand cate by ae the ‘Patiem=" parameter in a WN. N ie 


Use WriteProfileString() to change tie WIN.INI file. 
Set to 0. 
Set to NULL. 


Change the bitmap used for the desktop background. 

Set to 0. 

A pointer to a character string that contains the name of the bitmap file. 

Change the vertical distance within which a second mouse button click must occur to be 
registered as a double-click. 

Set to the double-click vertical height in pixels. 


‘Set to NULL. 


Change the maximum number of milliseconds between two mouse button clicks to have the 
second click register as a double-click. 


t to double-click time in milliseconds. 
Set to NULL. ; 
Change the horizontal distance within which a second mouse button click must occur to be 
registered é as a double-click. 
Set to the double-click horizontal height in pias. 
Set to NULL. 


Change the size (granularity) of the desktop sizing grid. 

Set to the grid size. 

Set to NULL. 

Tum title wrapping of icon title strings on or off. 

Set to TRUE to tum title wrapping on, FALSE to tum title wrapping off. _ 


_ Set to NULL. 


Change the keyboard delay setting.. 
Set to the new delay value. 
Set to NULL. 


Change the keyboard autc-repeat speed. 
Set to the new auto-repeat speed. 
Set to NULL. 


Change the alignment of popup menus relative to the corresponding item in the top menu bar. 
_ Set to TRUE for right alignment, FALSE for left alignment. 


Set to NULL. 


Change the mouse speed and the X and Y mouse threshold values. Movements smailer than 


the threshold do not resutt in mouse activity. 
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wParam Set to 0. 


IpvParam Set to a pointer to a thiee integer array (int value[3]) where: 
value{O] = new X direction mouse threshold; 
value{1] = new Y direction mouse threshold; 
value[2] = new mouse speed value. 


Table 3-15. SystemParametersInfo() wActionValues. 


SWinIni WORD: This value determines if any changes made to system settings are recorded in the WIN.INI 
file, and if the WM_WININICHANGE message is broadcast to all applications after the change is 
made. Changing WIN.INI causes the new system settings to be used in subsequent Windows ses- 
sions, as WIN.INI is read when Windows starts. Possible settings are shown in Table 3-16. 


NULL No change to WIN.INI. 
SPIF_UPDATEINIFILE Writes the new system parameters to the WIN.INI file. 
SPIF_SENDWININICHANGE — Writes the new system parameters to the WIN.INI file, and broadcasts the WM_WININICHANGE 


message to all applications running on the system. 


Table 3-16. SystemParametersInfo() Flag Seitings. 


Related Messages WM_WININICHANGE\ 


‘Example This example increases the width of the border of every win- 
dow running on the system when the user clicks the “Do It!” 
menu item. The borders are all restored to normal width when [Saas RaSumBmenHsecaiom Eas 
the application exits. (See Figure 3-16.) Figure 3-16. SystemPara- 

metersInfo() Example. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD 
wParam, LONG lParam) 


t 1 
static int nOldBorderWide ; 
switch (iMessage) ; /* process windows messages */ 
{ 
case WM_CREATE: /* save original window border width */ 
SystemParametersInfo (SPI_GETBORDER, 0, &nOldBorderWide, 
NULL) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ /* increase border width * 5 */ 


case IDM_DOIT: 
_ SystemParametersInfo (SPI_SETBORDER, 
€& 5 * nOtdBorderWide, NULL, NULL) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hwnd) 4 


break ; 
} 
break ; 
case WM_DESTROY: — /* set border width back to normal */ 


SystemParametersiInfo (SPI_SETBORDER, nOldBorderWide, 
NULL, NULL) ; 
PostQuitMessage (0) ; 
break ; ; 
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default: 
return DetWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 

} 

UNREGISTERCLASS OWin2.0 OWin3.0 sWin3.1 

Purpose Frees the memory holding an unneeded class description. 

Syntax BOOL UnregisterClass(LPSTR lpClassName, HANDLE hJnstance); 

Description * This function completely removes the window class from the system. Make sure all windows based 
on the class are destroyed before the class is eliminated. 

Uses In applications with several modules. UnregisterClass() can be used to free memory space if the 
new module does not need certain classes. Classes registered within an application are destroyed 
automatically when the application terminates. 

Returns BOOL. TRUE if the class was removed, FALSE if the class could not be found, or if a window exists 
that uses this class. 

See Also RegisterClass() 

Parameters . 

lpClassName LPSTR: A pointer to a null-terminated character string containing the class ndme. Do not at- 
tempt to remove predefingd window classes, such as buttons and edit controls. 

hInstance HANDLE: The handle to the program instance that created the class. 

Example - Inthis example, clicking the “Do It!” menu item causes the popup window to be destroyed, and its 


class to be unregistered. Note that the child window’s procedure does not issue a 
PostQuitMessage() function call when it gets a WM_DESTROY message. If it did, removing the 
popup would close the parent application program as well. 

The ChildProc() function needs to be referenced in the EXPORTS section of the program’s 
.DEF definition file, and a function prototype added to the header file. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


static WNDCLASS wndclass ; /* the window class */ 
static HWND hPopup ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_CREATE: /* build the child window when program starts */ 


wndclass.style 
wndclass.lpfnWndProc 


CS_HREDRAW [| CS_VREDRAW | CS_PARENTDC; 
ChildProc ; 


, wndclass.cbClsExtra 0; 

wndclass.cbWndExtra 0; 
wndclass.hInstance ghInstance ; 
wndclass.hIcon NULL ; 


wndclass.hCursor 
wndclass.hbrBackground 
wndclass.tpszMenuNam 
wndclass.lpszClassNa 


LoadCursor (NULL, IDC_ARROW) ; 
GetStockObject (LTGRAY_BRUSH) ; 
NULL ; 
"“SecondClass" 

/* register the window class */ 
if(RegisterClass (&wndclass)) 
{ F 


: hPopup = CreateWindow ("SecondClass", "Popup Window", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 50, 200, 150, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChPopup, SW_SHOW) ; 
} 


break : 
cafe WM_COMMAND: : /* process menu items */ 
switch (wParam) ae 
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{ 
case IDM_DOIT: , /* User hit the "Do it" menu item */ 
DestroyWindow (hPopup) ; 
UnregisterClass ("SecondClass", ghInstance) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ;. : 
3 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return COL) . 


/* Here is a separate message processing procedure for the child window */ 


long FAR PASCAL ChildProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
switch (iMessage) /* process windows messages */ 
case WM_DESTROY: 
break ; : 
default: /* default windows message processing */ 
, return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; . 
} 
WinpDOoWF RoMPoIntT  OWin20 CWin3.0 m@ Win 
Purpose Finds which window (if any) is at a given point on the screen. 
Syntax HWND WindowFromPoint(POINT Point); 
Description Finds a window based on the screen coordinates given in Point. 
Returns A handle to the window occupying the given point on the screen. NULL if no window is at that 
point. 
See Also ChildWindowFromPoint() 
Parameters : 
Point POINT: A point structure holding the x and y coordinates of the screen coordinates to check. 
POINT is defined in WINDOWS.H as 
typedef struct tagPOINT 
{ 
int xE> 
int y; 
} POINT; 7 
typedef POINT *PPOINT; = 
Example This example shows the title of the window located at screen coordinates 100,100 (from the top 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


left corner) when the “Do It!” menu item is clicked. 


HDC hdc ; 

char cBuf C25] ; 

HWND FoundWindow ; 

POINT pScreen ; 

switch (iMessage) | /* process windows messages */ 
{ 
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case WM_COMMAND: 
switch (wParam) 


[Other program lines] 


/* process menu items */ 


case IDM_DOIT: : /* User hit the “Do it" menu item */ 


pScreen.x = 100 ; 
pScreen.y = 100 ; 
hFoundWindow = WindowFromPoint (pScreen) ; 
hDC = GetDC (hWnd) ; 
TextOut ChDC, 10, 10, 
_ “At 100, 100 is the window:", 26) 
if ChFoundWindow) 
4 


Ne 


GetWindowText (hFoundWindow, cBuf, 24) ; 
TextOut (hDC, 15, 25, cBuf, strlen (cBuf)) ; 
} : 
else 
TextOut Choc, 15, 25, “None found", 10) ; 
ReleaseDC (hWnd, hDC) ; 

break ; : 


108 


Menus are used in essentially every Windows program to allow the user to select actions as the program is running. 
The Windows Software Development Kit.(SDK) provides a comprehensive set of tools for building menus and modify- 
ing them as the program runs. 


Main Menus and Popup Menus 
Windows recognizes two basic types of menus: top-level menus sand popup menus. The top-level menu (also called the 
“main” menu of a program is the series of commands that are visible in the window's menu bar at all times, assuming 
the program has a menu. For simple programs, the menu bar will contain all of the program’s menu options. If there 
is not enough room for all of the menu items on one line, Windows will automatically “break” the line, creating a two- 
line menu bar. For more complex programs, there is not enough space on the menu bar for all the commands you may 
need. This is where popup menus (sometimes called submenus, “pull down,” or “drop down” menus come in. When 
clicked, the top menu bar items can spawn popup menu items with many more options from which to choose. Figure 
4-1 shows a typical example. 


Building Menus in the Resource File 


For most programs, defining a menu is simply a matter of writing a few lines in the resource .RC file. Here is an 
example which produces the menu structure shown in Figure 4-1. 


; ns ae ee ean 
> GENERIC.RC Resource Script File : Es genmeny Sin 
| Top item Quit Help 

/* genmenu.rc 1 %*/ : 
Hinclude <windows.h> 
#include “genmenu.h" 


genamenu ICON generic.ico 
genmenu MENU 
BEGIN ; ; Popup Menu 
POPUP "&Top Item", . E 
BEGIN 
MENUITEM "Item &0ne", IDM_POP1 ° 
MENUITEM "Item &Two". | IDM_PoP2 Figure 4-1. Top Level Menus 
END and Popup Menus. 
MENUITEM "SQuit", _ -IDM_quit 
MENUITEM “\aGHelp", IDM_HELP 
END 


In this case there are three items on the top level menu bar, “Top Item,” “Quit,” and “Help.” The first item is a 
headline for a popup menu containing “Item One” and “Item Two.” The values behind the menu item ID numbers 
(IDM_POPI, etc.) are defined in the program's header file as a series of integers. They should be numbered between 
0 and Ox7FFF. The numbering sequence is not important. 

There are a few extra things to notice about this menu definition. The ampersand (&) characters are used to 
create keyboard alternatives to clicking menu items with the mouse. The letter following the ampersand is underlined 
in the menu. Holding down the (air) key and the key for the underlined letter causes that menu item to be selected. 
This amounts to an almost instant keyboard interface. If you need to display the ampersand character, use a double 
ampersand (&&). If more than one menu item has the same letter preceded by an ampersand, the first one will be 
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underlined and will respond to the Gi) key combination. A double quote (“”) will insert a single quote mark in a 
_ string. Within popup menus, you can also use it for a tab character. This will not work on top-level menus. Also note 

that the “Help” item is preceded by “\a”. This moves that item to the Tight side of the window’s menu bar. This is 

typically used for help information menus. 

Menu definitions can also include commands for changing the way a menu item is displayed. “Graying” a menu 

item causes Windows to display the menu letters with gray text, rather than the usual black. Graying is used to give a 
’ visible indication'that a menu item is not operating at a given time. Typically grayed items are also disabled, so that no 
Windows’ messages are sent if the user attempts to select the item. Menu items can also be checked, which means 
that a small checkmark is displayed to the left of the menu item. This is handy when there are options that the user 
can turn on or off, but not enough options to justify a dialog box with radio buttons to make the selection. You can also 
control where menus and submenus break, if you use multiline menus. 

The control over graying, checking, etc. within the resource .RC file menu definition is achieved by adding the — 

control word to the end of a MENUITEM statement. For example, here is a menu definition with two levels of popup 
menus, a grayed item, a checked item, and a specificaticn of a break in a popup menu. 


C> Resource Scri»t File with Menu Items Grayed and Checked 
/* genmenu.rc x; 

#include <tiindows . h> 

#include “geanenu.h" 

* genmenu ICON generic.ico.. 


genmenu MENU ‘ 7 } 
_ BEGIN 
POPUP "&First Menu" 
BEGIN 
MENUITEM "§Top Item", IDM_TOP1 
MENUITEM "81st Option", _IDM_OPT1, CHECKED 
. MENUITEM “&2nd Option", IDM_OPT2, GRAYED 
MENUITEM SEPARATOR 
POPUP "“&Popup"” ; 
BEGIN a ; ; 
‘MENUITEM "&Left One", IDM_. POP1. 
MENUITEM “&Right One", IDM_POP2, MENUBREAK 
END 
END . 
MENUITEM "“&Quit", IDM_QUIT 


MENUITEM “\a&Help", DM_HELP, HELP 
END : 


The full list of menu item options is given in Table 4-1. 


Meaning 
CHECKED The item has a checkmark next to it. 
_ GRAYED The item’s text is inactive and appears in gray letters. 
HELP . The item has a vertical line to the left. You may also want to put the characters “\a” at the beginning of the 
menu text to force this item to the menu bar's far right side. 
INACTIVE The item name is displayed, but cannot be selected. No WM |_ COMMAND ree are sent from this 


item until it is enabled. 


MENUBARBREAK For menus, places the item on a new line, creating a multiline menu. For popups, places the new item ona 
new column, creating a multicolumn (rectangular) popup menu. A line is used to separate this item from the 
previous one. 


MENUBREAK Same as MENUBARBREAK, except for popup menus. For menus, places the item on a new ine, creating a : 
multiine menu. For popups, places the new item on a new column, creating a multicolumn vecengiay 
popup menu without a dividing line. 


Table 4-1. Menu Item Options-—Used to the Right of the Menu Item. 
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Popup menu names (the line that says “POPUP” in the resource file) can also use all of these parameters, but do 
not have a menu item ID value associated with them. Only the items within the popup menus have ID values for 
selection. You can also place a line between any two menu items by using MENUITEM SEPARATOR as a menu item. 
The line cannot be selected, but can help it to clarify long popup menus by breaking the list into logical sections. 


Adding a Menu to the Program’s Window 


Defining a menu in the resource .RC file does not automatically make it visible, or make it a part of the progratn’s 
window. Normally, you will attach the program’s menu to the window's class definition in the WinMain() function. 
This is done by setting the IpszMenuName element of the wndclass structure to point to the menu name. 
RegisterClass() then associates this menu name with any window created from the class. 


wndclass.style CS_HREDRAW | CS_VREDRAW ; 


wndclass.LpfnWndProc WndProc ; 
wndclass.cbClsExtra 0; 
wndclass.cbWndExtra 0; 


wndclass.hInstance 
wndclass.hlIcon 
wndclass.hCursor 


hInstance ; 
LoadIcon (hInstance, gszAppName) ; 
LoadCursor (NULL, IDC_ARROW) ; 
wndclass.hbrBackground GetStockObject (WHITE_BRUSH) ; 
wndclass. lpszMenuName “genmenu" 
wndclass.lpszClassName = "generic" 
/* register the window class */ 

if C!RegisterClass (&wndclass)) 

return FALSE ; 


The menu name can be any valid name. The name in the class definition must match the one defined in the 
resource file for the menu. 


Changing Menus 


Normally, you will use the resource .RC file to define the menu. If your program allows the user to add new menu 
options (such as macro names), you may need to modify menu items or build entire new menus after the program 
starts running, New menus are created with the CreateMenu() function. The new menu is initially empty. Menu items 
are added to the menu using AppendMenu() and InsertMenu(). As soon as the menu is built, you can attach it to the 
window using SetMenu(). The memory associated with an old, unneeded menu can be freed using DestroyMenu(). 
You can also create new popup menus by using CreatePopupMenu(). Items are added to the popup menu using 
AppendMenu() and InsertMenu(), just like a main menu. When the popup is built, it can be added to the menu using 
AppendMenu() or InsertMenu(). If your program switches between a few fairly constant menus, you will probably find 
it simpler to define all of the menus in the resource .RC file. Each menu is given a different name. During the execu- 
tion of the program, you can switch between menus by calling LoadMenu() to make the menu available and SetMenu() 
to attach it to the program’s window. LoadMenu() only loads one copy of the menu into memory. You can call it 
multiple times without wasting memory. If you use two or more predefined menus, only one will be attached to the 
application’s main window at any one time. Only the attached menu will end up removed from memory when the 
application terminates. Use DestroyMenu() to remove any other menus as the program exits, to avoid tying up 
memory. 

Essentially, every aspect of a menu can be changed as the program is running. The most common changes are to 
change a menu's character string, check and uncheck menu items, gray and disable them, and to delete items. 
ModifyMenu() allows several of these operations to be carried out in one function call. There are also more specific 
functions for single operations, such as DeleteMenu() to remove an item, CheckMenultem() to add and remove: 
checkmarks, and EnableMenultem() to enable and disable items. If you change the top-level menu, be sure to call 
DrawMenuBar(). This causes the menu bar to be redrawn. Otherwise, the changes will not become visible until the 
user attempts to select a menu item. This is not necessary if the changes are made while processing the WM_CREATE 
message, as that message is processed before the window is drawn for the first time. 
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Bitmaps as Menu Items 


Menu items are normally text strings. In some cases it may be far better to have ; a 
visual image for the menu items, rather than using words. Good examples are the 
“tools” items for paint programs. A picture of a brush is more intuitive than the 
word “Brush.” Figure 4-2 shows a simple example with two menu items, a pen anda 
pair of scissors. 

You cannot define a bitmap menu item in the resource .RC file. Instead, you 
add or insert the bitmap item into the menu using AppendMenu() and Insert-_ 
Menu(). Typically, the menu bitmaps are created using the SDKPaint program that | 
comes with the software development kit. A 32 by 32 pixel bitmap is goodforasmall Figure 4-2. Hitmane As Mew 
menu item, while 64 by 64 pixels makes a big one. The bitmaps are referenced in Items. 
the top of the resource file. A typical series of AppendMenu() function calls ie load 
in a menu containing bitmaps is 


hMenu = CreateMenu () ; 

hSubMenu = CreatePopupMenu () ; 

hPen8m = LoadBitmap (ghInstance, (LPSTR) “pen") ; 

hCutBm = LoadBitmap (ghInstance, (LPSTR) “cut") ; 

AppendMenu ChSubMenu, MF_BITMAP, IDM_POP1, (LPSTR)CLONG)hPenBm) ; 
AppendMenu (hSubMenu, MF_BITMAP, IDM_POP2, (LPSTR) (LONG) hCutBm) ;. 
AppendMenu ChMenu, MF_POPUP, hSubMenu, (LPSTR) “&Tools") ; 
AppendMenu (Chenu, MF_STRING, IDM_QUIT, (LPSTR) "“&Quit") ; 
AppendMenu (hMenu, MF_STRING, IDM_HELP, (LPSTR) “&Help") ; 

SetMenu (hWnd, hMenu) ; } 


In this case, the bitmaps are loaded into a popup menu. The popup menu is then appended to the main menu with 
the popup heading of “Tools.” Two normal menu items “Quit” and “Help” are then added, before the menu is attached 
- to the program’s window with SetMenu(). The resulting menu structure is shown in Figure 4-2. A more complet 
listing of this program is given in the AppendMenu() function description. 

Windows automatically sizes the popup menu to accommodate the largest bitmap loaded. Windows does not put 
a border around the bitmaps, so you may want to draw the borders when you create the bitmaps in SDKPaint. 


The Checkmark Bitmap 


A new addition with Windows version 3.0 is the ability to change the bitmap used to show a checkmark next to a 
checked menu item. This gets a little involved, as the size of the checkmars depends on the video resolution of the 
screen on which the program is displayed. 

GetMenuCheckmarkDimensions() retrieves the size of the menu item checkmarks, while SetMenultemBitmaps() 
establishes a new bitmap for a menu item to use for checkmarks. You can go wild and have a different checkmark 
bitmap for each menu item. Don’t confuse meee functions with loading piemape a8 as 

_the menu items themselves. 


Owner-Drawn Menu Items | 


The most flexible, but most complex, of the menu options is the owner-drawn style. 
In this case your program paints directly on a popup menu, which is a little win- 
~ dow. This allows you to scale graphics images to match the resolution of the screen 
or the size of the parent window. As an example, consider a program that has two 
graphics images for the first two popup selections. For simplicity, we will use a 
blue rectangle and ared ellipse as the choices. The window willappearasshownin Figure 4-3. Owner-Drawn 
Figure 4-3 when the first top-level menu item is selected. Menu Items. 


_ Like bitmaps, this type of menu cannot be created from within a resource 
script file. The menu must be built from within the program. The key to creating owner-drawn menu items is to use the 
MF_OWNERDRAW flag when AppendMenu OF is used to add the items. Listing 4-1 shows the code to create and use the 

Menu shown j in Figure 4-3. 
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> Listing 4-1. WndProc() Function Creating Owner-Drawn Menu Items 
tong FAR PASCAL WndProc CHEND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : % 


HHENU hMenu, hSubMenu ; 

LPMEASUREITEMSTRUCT MIS ; 

LPDRAWITEMSTRUCT DIS ; 

static DWORD. dwRColor, dwEColor ; . 
HBRUSH hBeush ; 

static int nCheckWide ; 

switch (iMessage) /* process windows messages */ 

{ 


case WM_CREATE: 
hMenu = CreateHenu () ; 
hSubMenu = CreatePopupMenu () ; 
AppendMenu (hSubMenu, MF_LOWNERDRAW, IDM_POP1, 
CLPSTR) CDWORD) RGB (0, 0, 255)) ; 
AppendMenu (hSubMenu, MF_OWNERDRAW, IDM_POP2, 
CLPSTR) CDWORD) RGB (255, 0, 0)) ; 
AppendMenu (hMenu, MF_POPUP, hSubMenu, (LPSTR) “&Tools"> 
AppendMenu ChMenu, MF_STRING, IDM_QUIT, (LPSTR) “@Quit") 
AppendMenu (hMenu, HF_STRING, IDM_HELP, (LPSTR) "“&Help") 
SetMenu (hWnd, hMenu) ; 
nCheckWide = LOWORD (GetMenuCheckMarkDimensions ()) ; 
break ; 
case WM_MEASUREITEM: 
MIS= CLPMEASUREITEMSTRUCT) (Param ; 
if (MIS->itemID == IDM_POP1) /* rectangle item */ 
{ 


Me Wo Neo 


NIS->itemWidth = 64; 
MIS->itemHeight = 64 ; 
dwRColor = M1S->itemData ; 


} 
else if (HIS->itemID == IDM_POP2)/* ellipse */ 
{ 


MIS->itemWidth = 64; 
MIS->itemHeight = 64 ; 
Z dwEColor = MIS->itemData ; 
} 
return (COL) ; 
case WM_DRAWITER: 
DIS = (LPDRAWITEMSTRUCT) tParam ; 
if (DIS<>itemID == IDM_POP1) /* rectangle */ 
{ 3 
if (DiS->itemState == ODS_ SELECTED) 
hBrush = * GetStockObject (BLACK_BRUSH) ; 
else 
hBrush = CreateSolidBrush (dwRColor) 
SelectObject (DIS->hDC, hBrush) ; 
Rectangle (DIS->hDC, nCheckWide, 0, 
64 + nCheckWide, 64) ; 


} 
else if (D1IS->iteml1D == IDM_POP2) 
{ 
if (DIS->itemState == ODS_SELECTED) 
hBrush = GetStockObject (BLACK_BRUSH) ; 
else 
hBrush = CreateSolidBrush (dwEColor) ; 
SelectObject (DIS->hDC, hBrush) ; 
Ellipse (DIS->hDC, nCheckWide, 65, 64 + nCheckWide, 
128) ; 
} 
SelectObject (biS->hDC, GetStockObject ey eee 
Deletedbject ChBrush) ; 
break ; ' 
case WH COMMAND: /* process menu items */ 
switch (wParam) 
{ 
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case IDM_POP1: 
MessageBox (hWnd, “The SA es was selected", 
“Message”, MB_OK) ; 
break ; 
case IDM_ Pop2:” 
MessageBox (hWnd, “The ellipse s was selected", 
"Message", MB_ OK) ; 
break ; 
case IDM_QUIT: 
PostQuitMessage (NULL) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ;_. 
break ; 
default: ’ '/* default windows message processing */ 
return DefWindowProc Chuind, iMessage, wParam, (Param) ; 
} 
return (OL) ; 


The menu is created when the WM_CREATE message is processed. Two of the menu items are set to 
MF_OWNERDRAW. AppendMenu() has the ability to associate a 32-bit value with the menu item. This ability does not 
have to be used, but it is a convenient way to pass the color of an owner-drawn menu item. This is done in the example 

_ code, using the RGB() macro to specify the desired color value. 

Drawing the owner-drawn menu items is a matter of processing two Windows messages. WM_MEASUREITEM is 
sent when a menu is activated that contains owner-drawn items. This is the same message used for owner-drawn 
buttons, list boxes, and combo boxes. The {Param value passed with the message points to a MEASUREITEMSTRUCT 
structure. This is defined in WINDOWS.H as . 


/* MEASUREITEMSTRUCT for ownerdraw */ We 
typedef. struct tagMEASUREITEMSTRUCT 
{ 


WORD CtlType; - /* ODT_MENU, ODT_LISTBOX, ODT_COMBOBOX; ODT_BUTTON *] 


WORD CtlIo;  /* not used with menu items */ 2 
WORD itemID; /* the menu item's id number */ 

WORD itemWidth; /* the program fills in these two values to set */ 
WORD itemHeight; /* the size of the menu item in pixels */ 

DWORD itemData; /* the 32-bit data from AppendMenu ends up here */ 


} MEASUREITEMSTRUCT; 
typedef MEASUREITEMSTRUCT NEAR *PMEASUREITEMSTRUCT; 
typedef MEASUREITEMSTRUCT FAR *LPMEASUREITEMSTRUCT; 


The program must set the itemWidth and itemHeight values when it processes the WM. _MEASUREITEM mes- 
sage, and then it must return to Windows. This is how the program specifies how big the owner-drawn menu item(s) 
will be. This message is processed once for each owner-drawn menu item in the currently active menu. The actual 
drawing of the menu items occurs when WM_DRAWITEM messages are sent from WINDOWS. This is a little more 
complex than you might expect, as the owner-drawn menu item can do graying, checking, changing shape or color on 
selection, etc. The /Param value passed with WM_DRAWITEM is a pointer to a DRAWITEMSTRUCT data structure, 
~ defined in WINDOWS.H as 


/7* DRAWITEMSTRUCT for ownerdraw. */ 
typedef struct tagDRAWITEMSTRUCT 
{ 


WORD ; CtlType; /* ODT_MENU, ODT_ LISTBOX, ODT COMBOBOX, ODT BUTTON Tc 


WORD ctliIbd; /* not used with menu items */ 

WORD itemID; /* the menu item's id number */ 

WORD itemAction; /* ODA_DRAWITEM, ODA_SELECT, or ODA_FOCUS */ 

WORD itemState; /* ODS_SELECTED, ODS_GRAYVED, ODS_DISABLED,ODS_CHECKED a] 

HWND hwndItem; /* the item's handle */ ; /* or ODS_FOCUS */ 
- HDC _ hdc; _ /* the item's device context */ 
_ RECT _reItem;. . /* the bounding rectangle of the item Py, 

“DWORD itemData; /* here is where the 32-bit data goes af 
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} DRAWITEMSTRUCT; 
typedef DRAWITEMSTRUCT NEAR *PDRAWITEMSTRUCT; 
typedef DRAWITEMSTRUCT FAR *LPDRAWITEMSTRUCT; 

This is a convenient structure, as it contains both the menu window's handle (the menu is a window), bounding 
rectangle, and device context. The 32-bit value set by AppendMenu() is also available. The program can modify the 
painting operation depending on the state of the menu (grayed, selected, checked, etc.). In the simple example above, 
the objects are painted black to show selection. One point of confusion here is that the entire popup menu is a single 
window. The painting operations for separate items must determine the correct location to paint each item within the 
menu. In the example, each menu item is 64 pixels high, so spacing is simple. Note that the items are offset to the right - 
by the width of a menu item checkmark, to be consistent with the normal shape of menu items. 


Menu Messages 

As mentioned above, Windows sends the WM_COMMAND message every time a menu item is selected. This is nor- 
mally the only message that you will process from'a:menu. However, you may find use for the WM_INITMENU and 
WM_INITMENUPOPUP messages. They are sent at right: ‘before a main menu or popup menu is activated. They provide 
some advance warning, in case the application needs to ‘change the status of items from enabled to disabled, re-create 
bitmaps, etc. The WM_MENUCHAR message is sent if the user attempts to use a keyboard shortcut key that does not 
match any of the menu names preceded by an ampersand character (&). This allows more than one keyboard shortcut 
to be programmed per menu item, or it can be used to display an error message. The WM_MENUSELECT message is 
also sent when a menu item is selected. This message is more versatile than the WM_COMMAND message, as it is sent 
even if the menu item is grayed. Normally, this message is used for warning messages. The messages are documented 
in Chapter 9, Window Messages. 


Menu Function Summary 


Table 4-2 summarizes the menu support functions. The detailed function descriptions follow immediately after the 
table. 


aa Adds a new menu item to the end of a menu. 


CheckMenultem Checks or unchecks a menu item. 

CreatePopupMenu Creates a popup menu 

CreateMenu Create a new, empty menu. 

DeleteMenu Removes an item from a menu. 

DestroyMenu Removes a menu from memory. 

DrawMenuBar Forces a window’s menu bar to be repainted. 

EnableMenultem ___ Changes a menu item to/from enabled and grayed. 

GetMenu Retrieves a handle to a window’s menu. 

GetMenuCheckMarkDimensions Retrieves the size and width of the bitmap used to create checkmarks next to menu items. 
GetMenultemCount a _ Gets the number of menu items in a menu. ; 
GetMenultem!D Retrieves the !D value associated with a menu item. 

GetMenuState . Finds the number of items in a menu, or the status of an item. 

GetMenuString Retrieves the label displayed in a menu item. . 

GetSubMenu Retrieves a handle to a popup menu. — . \ 
GetSystemMenu Retrieves a handle to the system menu. 

HiliteMenuttem Highlights a top-level menu item. 


InsertMenu . __ Inserts a new menu item into an existing menu. - 
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Table 4-2. continued 


Function >; + Purpose ose: 
LoadMenu | Retrieves a handle to a menu defined in the resource .RC file. 
ModifyMenu Changes the properties of a menu item. 

“ RemoveMenu | Removes a menu item from a menu. 
SetMenu Attaches a menu to a window. 
SetMenultemBitmaps Replaces the default menu checkmark bitmap with a custom bitmap. 


TrackPopupMenu Displays a submenu anywhere on the screen. 


Table 4-2. Menu Function Summary. 


APPENDMENU . ' OWin2.0 mWin3.0 wm Win3.l 
- Purpose Adds a new menu item to the end of a menu. , 

Syntax BOOL AppendMenu(HMENU hMenu, WORD wFlags, WORD wiDNewltem, LPSTR lpNewltem); 

Description Similar to InsertMenu(), except that PAnpendéendly only adds menu items to the end of the 
menu. 

Uses Creating menus from within the body of the program, instead of building them in the resource 
file. Also useful in modifying existing menus. 

Returns — BOOL. TRUE if the new menu item was added successfully, FALSE if not. 

See Also InsertMenu(), CreateMenu(), SetMenu(), DrawMenuBar() 

Parameters 

hMenu HMENU: A handle to the menu u being changed. Use cen to retrieve a window's menu 

. handle. 
wFlags ~ WORD: Specifies how the wIDNewItem and lpNewItem parameters are to be cre These. 


values can be combined using the C language binary OR operator (!)with any of the menu item 
control flags in Table 4-3. 


Meaning 
MF_BITMAP The menu item will be a bitmap. The low-order word of the peal parameter should contain a 
handle to the bitmap. 
MF_CHECKED _Places a checkmark next to the menu item. 
MF_DISABLED Makes it impossible to select the menu item. Does not gray the menu item. — 
MF_ ENABLED Makes it possible to select the menu item. This is the default. 
MF _ GRAYED Grays the menu item text and disables the menu item so that it cannot be selected. 


| MF - MENUBARBREAK _ In popup menus, it separates a new column of items and displays a separator bar between them. In 
main menus, it starts a new line of menu items. 


MF_MENUBREAK In popup menu, it separates a new column of items. No separator bar is displayed. In main menus, it 
breaks the menu into a new line of menu items (two rows of menu items at the window's top). 


MF_OWNERREDRAW __ Specifies that the parent window is to. paint the menu item each time it is needed. ‘This is not possible 
for the top menu line, but can be done for drop-down and popup menu items. The parent window will 
receive WM_MEASUREITEM and WM_DRAWITEM messages to update the drawing area. 


MF_POPUP Specifies a popup menu. The wiDNewltem parameter will be a handle to the popup menu. 


MF_SEPARATOR Draws a horizontal line in the menu. This line cannot be selected, checked, enabled, or ane The 
loNewltem and wiDNewltem Peateias are ignored. 
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MF_STRING Specifies that the new item is a character string. /oNewltem points to the string. 
MF_UNCHECKED Does not place a checkmark next to the menu item. This is the default. 


Table 4-3. AppendMenu() Flags. 


lpNewlItem LPSTR: Points to the contents of the new menu item. The type of data depends on the wFlags 
setting, as described in Table 4-4, 


IpNewltem 
MF_STRING Long pointer to a character String. 
MF_BITMAP A bitmap handle. The bitmap handle is stored in the low-order word of JoNewitem. Use 
LoadBitmap() to retrieve this value. 
MF_OWNERDRAW You specify to what the 32-bit value IpNewltem points. Windows will send WM_MEASUREITEM . 


and WM_DRAWITEM messages to the window's message processing function when the menu 
item needs to be redrawn. The value in the joNew/tem parameter will end up passed to the 
window’s function as an element of the structures pointed to by the /Param value. See the 
example owner-drawn menu at the beginning of this chapter. 


Table 4-4. AppendMenu{) Data Types. ae “genienuias Sal 


Related Messages WM_MEASUREITEM, WM_DRAWITEM 


Example Here the program does not have a menu specified in the re- 
source .RC file. Instead, the menu is created when the pro- 
gram starts up. Figure 4-4 illustrates the following example. 


© The Program Header File 


/* genmenu.h */ 
#define IDM_TOP1 
#define IDM_QUIT 
#define IDM_POP1 
#define IDM_POP2 
H#define IDM_HELP 
/* global variables */ 
int ghInstance ; 
char gszAppName CJ = “genmenu" 
/* function prototypes */ 
Long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 


/* menu item id values */ 


Figure 4-4. AppendMenu() 
Example. 


AONAN = 


The Resource .RC File 
Note that the two bitmaps which will be used in the menu are named here. Also note that no menu is defined, as it will 
be created within the program logic. 


Co Resource File 
/* genmenu.rc */ 
Hinclude <windows.h> 
H#include "“genmenu.h* 


genmenu ICON generic.ico 3 

pen . BITMAP pen.bmp 
cut ' BITMAP cut.bmp 
The WinProc() Function © 


The menu is created when the program starts execution (WM_CREATE message received). The main menu, and the 
popup menu containing the bitmaps, are created one item at a time. DrawMenuBar() is not required in this case, as 
the WM_CREATE message is processed before the window and menu bar are painted the first time. 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . 


a HMENU hMenu, hSubMenu ; 
static HBITMAP hPenBm, hCutBm ; 
switch (iMessage) /* process windows messages */ 
{ 


-case WM_CREATE: [* build the progran® s menu at startup */ 
hMenu = CreateMenu () ; 
hSubMenu = CreatePopupMenu ©); oe : 
- hPenBm = LoadBitmap (ghInstance, (LPSTR) “pen") 


tA 
hCutBm = LoadBitmap (ghInstance, (LPSTR) “cut™) ; 
AppendMenu (hSubMenu, MF_BITMAP, IDM_POP1, 
CLPSTR) CLONG) hPenBm) ; ey, 
AppendMenu (hSubMenu, MF —BITMAP, IDM_POP2, 
(LPSTR)CLONG)hCutBm) ; 
AppendMenu ChMenu, MF_POPUP, hSubMenu, 
: (LPSTR) "&Tools") ; 
AppendMenu (hMenu, MF _STRING, IDM | Quit, 
CLPSTR) "“&Quit") ; 
AppendMenu (hMenu, MF_STRING, IDM_HELP, 
CLPSTR) “&Help") ; 
SetMenu (hWnd, hMenu) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) : 
case IDM_POP1: /* Prove that bitmap menu item works! */ 


MessageBox (hWnd, “The pen tool was selected", 
SSPE MB_OK) ; 
break ; 
case IDM_ Pop2:” : 
MessageBox (hWnd, "The cut tool was selected", ; 
“Message”, MB_OK) ; 
break ; 
case IDM_QUIT: 
DestroyWindow ChWnd) ; 
break ; 
} 
break ;. 
case WM_DESTROY: /* stop application */ 
DeleteObject (hPenBm) ; 
DeleteObject (hCutBm) 
PostQuitMessage (0) ; 


Ne Ne 


aebeie : /* default windows message processing a) 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
rates COL) ; | 

: 
CrECKMENUITEM . | wWin2.0 mwWind0 wWin3.1 
Purpose Checks or unchecks a menu item. 
Syntax BOOL CheckMenultem(HMENU hMenu, WORD wlDChecklitem, WORD D wCheck): 
Description ~ Works for both main menu items and popup menus. 
Uses Checkmarks generally are used to signify that an option has been turned on or off. For large 

numbers of options, use a dialog box with radio buttons for selections. 
Returns Returns the previous value of the item, MF_CHECKED or MF _| UNCHECKED. Returns~—1 on error. 
See Also GetMenuState(), Bran eneuuen) ModifyMenu() 
Parameters . 
hMenu HMENU: A handle to the menu. Use GetMenu() to retrieve a window's menu. 
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wlDCheckltem WORD: The menu item number to be checked or unchecked. 


wCheck WORD: Specifies how the command is to be executed. Two of the following four possibilities, see 

Table 4-5, are always combined with a C language binary OR operator (|) to make the wCheck 

parameter. 
. . Meaning © 

MF_BYCOMMAND The niDCheckitem value is the menu item ID value. 

MF_BYPOSITION The nlDCheckitem value is interpreted relative sequential yan of existing menu items: 0 
a is the first item, 1 the second, etc. 

_MF_CHECKED Places a checkmark next to the menu item. 

MF_UNCHECKED Does not place a checkmark next to the menu item. 


Table 4-5. CheckMenultem() Flags. 


Related Messages WM_MENUSELECT 


Example Here the menu item IDM_OPT! toggles between being checked and unchecked each time it is 
selected. Note that GetMenuState() is used to find the current menu item status (checked or 
unchecked). ie 


Long FAR PASCAL WndProc CHWND pee unsigned iMessage, WORD wParam, LONG lParam). 
{ 


HMENU : hMenu ; 
BOOL bChecked : 
switch Cittessage) /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_OPT1: 
hMenu = GetMenu (hWnd) ; 
bChecked = GetMenuState ChMenu, IDM, _OPT1, 
MF_BYCOMMAND) ; . 
if (bChecked & NF_CHECKED) : 
CheckMNenultem (hMenu, IDM_OPT1, 
MF_BYCOMMAND | MF_UNCHECKED) ; 


L 
aio CheckMenultem (hMenu, IDM_OPT1, 
MF_BYCOMHAND | MF_CHECKED) ; 
break ; 
[Other program lines] | | 
CREATEPOPUPMENU | OWin2.0 wWin30 wWin3.1 
Purpose Creates an empty popup menu. : | os 
Syntax - -  HMENU CreatePopupMenu(void); © oe 
Description Any menu other than the top menu bar is considered to be a popup menu. This furietion creates 
an empty popup menu, ready to have items added using AppendMenu() and InsertMenu(). 
Uses . Creating menus within the body of a program. Can be used with Track Popup Meau() to create 
* floating popup menus (menus not attached to éther.menus). 
Returns ‘  Ahandle to the menu created. NULL if a menu cannot be created. 
‘See Also *—~—Ss CreateMenu(), AppendMenu(), InsertMenu() ¥ 
Parameters None (void). 
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Example Here the program creates its menu on startup. The popup menu is created with two items, a text 
item “First Popup” and a bitmap “pen.” The main menu is then created. The popup menu is added 
__as the second item in the main menu. Finally, the completed menu is attached to the window 


with SetMenu(). 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
¢ : ' 
HMENU hMenu, hPopup ; 
“HBITMAP hBitmap ; 
switch (iMessage) /* process windows messages */ 
t % 


case WM_CREATE: 
hPopup = CreatePopupMenu () ; 
hBitmap = LoadBitmap (ghInstance, “pen") ; 
AppendMenu (hPopup, MF_STRING, IDM_OPT1, "First Popup") ; 
AppendMenu ChPopup, MF_BITMAP, IDM_OPT2, 

CLPSTR) CLONG) hBitmap) ; 

hMenu = CreateMenu () ; 
AppendHenu (hMenu, MF_STRING, IDM_TOP1, “First Main") ; 
AppendMenu (hMenu, MF_POPUP, hPopup, “Popup Item") . 
AppendMenu (hMenu, MF —STRING, IDM QUIT, | “Quit") ; 
SetMeny (hWnd, hMenud ; 


break ; 

[Other program lines] 
CREATEMENU BWin20 wWind.0 @Win3.l 
Purpose Creates a new, empty menu. . 
Syntax . HMENU CreateMenu(void); 
Description This is the first step in creating a menu within the body of an application program. Use 

AppendMenu() to add items to the menu, and use SetMenu() to attach the menu to a window. 
Uses Typically used to create menus for child windows. An alternative to defining all menus in the 


program’s resource .RC file. Menus created with this function cannot be floating menus. Use 
CreatePopupMenu() to create floating menus. 


Returns . HMENU, a handle to the menu created. 

See Also CreatePopupMenu(), AppendMenu(), SetMenu(), ModifyMenu() 

Parameters None (void). 

Example Here the program does not have a menu specified in the resource .RC file. Instead, the menu is 


created when the program starts. In this case, there are only two menu items. The IDM_TOPI 
and IDM_QUIT values need to be defined in the header file for this example to function. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HMENU hMenu ; : 
switch (iMessage) /* process windows messages */ 


case WM_CREATE: 
hMenu = CreateMenu() ; : 
AppendMenu (hMenu, Me STRING, IDM. _TOP1, “First Menu Item") ; 
AppendMenu ChMenu, MF_. STRING, IDM_QUIT, "Quit" ; 
ae tnenu ChWnd, hMenu) ; ‘ 


break ; 
case WM_ COMMAND: /* process menu items */ 
switch (wParam)’ 
{ ; 
case IDM_TOP1: /* User hit the “Help” menu item */ 


MessageBox (hWnd, “The first menu item was clicked”, 
“Message”, MB_OK |. MB_ICONASTERISK) ; 
break ; 


[Other program lines] 
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DELETEMENU OWin2.0 @Win30 mWin31 
Purpose Removes an item from a menu. 
Syntax BOOL DeleteMenu(HMENU AMenu, WORD nPosition, WORD wFlags); 


Description This function is poorly named, as it sounds like DestroyMenu(), which removes the entire menu 
from memory. DeleteMenu() only deletes a single menu item. If the menu item is a popup menu, 
the popup is destroyed, and its memory freed. Use DrawMenuBar() after this function to repaint 


the menu bar. 
‘Uses Small changes to menus as a program runs, This is an alternative to having more than one menu 
and switching between them. 
Returns BOOL. TRUE if the item was deleted, FALSE otherwise. 
~ See Also InsertMenu(), AppendMenu(), GetMenu(), DrawMenuBar() 
_Parameters 
hMenu HMENU: A handle to the menu. Use GetMenu() to retrieve a window’s menu. 
nPosition WORD: The menu item ID value. 
wFlags WORD: Specifies how the 2Position parameter is to be interpreted, as shown in Table 4-6. 
Meaning 
MF_BYCOMMAND The nPosition value is the menu item |D value. 
MF_BYPOSITION The nPosition value is interpreted relative sequential numbering of existing menu items: 0 is the 


first item, 1 the second, etc. 
Table 4-6. DeleteMenu() Flags. 


. Example Note that DrawMenuBar() is used immediately after DeleteMenu() to repaint the menu bar. 
Long FAR PASCAL WndProc (CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HMENU hMenu ; 
switch CiMessage) ‘/* process windows messages */ 
{ 

case WM_COMMAND: _ /* process menu items */ 


switch (wParam) 


case IDM_TOP1: /* Delete a menu item */ 
hMenu = GetMenu (hWnd) ; 
DeleteMenu (hMenu, IDM_TOP1, MF_BYCOMMAND) ; 
DrawMenuBar ChWnd) ; 


: break ; 
{Other program lines] 
DestroyMENU | | mWin2.0 mWin30 mWin31 
Purpose Removes a menu from memory. 
Syntax BOOL DestroyMenu(HMENU hMenu); 
Description Removes menus created in the resource .RC file and those created within the body of a program 
with the CreateMenu() function. | 
Uses Used with applications that have more than one menu. Only the menu attached to the 


application’s window will be deleted when the application terminates. Any other menus will re- 
main in memory. Use DestroyMenu() before the application terminates to free the memory con- 
sumed by the unattached menus. — . 


Returns BOOL. Non-zero if the menu was destroyed, NULL otherwise. 
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See Also CreateMenu(), CreatePopupMenu(), GetMenu() 

Parameters 

hMenu HMENU: A handle to the menu to remove. Use GetMenu() t to o find a whlows menu. 

Example The resource .RC file contains two menus that are loaded as resources into the program. The 


“genmenu” menu is attached to the program’s window i in the WinMain() function. The second 
menu “genmenu2” is held in reserve until it is time to change menus. 


/* genmenu.rc */ 
Hinclude <windows.h> 

#include "“genmenu.h" 

genmenu ICON generic.ico 


genmenu MENU 
BEGIN 
" POPUP "&First Menu" 
BEGIN P , 
MENUITEM “&Top Item (Change Menu)", IDM_TOP1 
MENUITEM "&ist Option”, IDM_OPT1, GRAYED 
MENUITEM “&2nd Option", IDM_OPT2 
END 
MENUITEM “&Quit", IDM_QUIT 


MENUITEM “\aSHelp", -IDMLHELP, HELP . 


END 
genmenu2 MENU 
BEGIN 
POPUP "&Second Menu" — 
BEGIN 
MENUITEM “&Revised Items", IDM_TOP1 
MENUITEM “&1st Option", IDM_OPT1 
MENUITEM “&2nd Option", IDM_OPT2, GRAYED 
MENUITEM "&3rd Option", IDM_OPT3 
END , 
MENUITEM “2Quit", IDM_QUIT 
MENUITEM "\aSHelp", IDM_HELP, HELP 
END 
Part of the WndProc() Function 


Note that the old menu is destroyed only if the new menu is successfully added to the window with SetMenu(). 
pone FAR PASCAL WndProc C(HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


HMENU hMenut, hMenu2 ; 
BOOL bStatus ; 
switch (iMessage) /* process windows messages */ 
c 4 7 
case WM_COMMAND:. 
switch (wParam) 
{ 
case IDM_TOP1: /* swap menus, destroy old one */ 
Menu1 = GetMenu Chiind) ; 
hMenu2 = LoadMenu (ghInstance, vgenmenu2") ; 
bStatus = SetMenu (hWnd, hMenu2) ; 
if (bStatus) 
DestroyMenu ChMenut) ; 


/* process menu items */ 


else eee 
MessageBox (hWnd, “Could not change menus.” 
: “Warning”, MB_OK | NB_ICONINFORMATION) ; 
: break ; 

[Other program lines] 
DrawMENUBAR ma Win20) mWin30) mWin3l 
Purpose Forces Saintinget of the window's menu bar. aoe 
Syntax void DrawMenuBar(HWND hWnd); 


' 
i 
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Description The menu bar is not part of the client region of the window and, therefore, is not updated when 


you use UpdateWindow(). 

Uses Use right after any change to the top-level menu. 

Returns No returned value (void). . 

See Also DeleteMenu(), GetMenuQ) 

Parameters 

hWnd HWND: A handle to the window which has the menu. Use mermenntyt to retrieve the window's 

~ menuhandle. ~ 

Related Messages WM_NCPAINT 

Example 

long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG (Param) 

. HMENU hMenu ; . - 
switch (iMessage) /* process windows messages */ 
: case WM_COMMAND: . _/* process menu items */ 


switch (wParam) ; 
t ; 
case IDM_TOP1: /* Delete a menu item */- 


hMenu = GetMenu (hWnd) ; 
DeleteMenu ChMenu, IDM_TOP1, MF_BYCOMMAND) ;_ 


DrawMenuBar (hWnd) ; 


break ; 
[Other program lines] F VEN 
y) * OT pce gd a 5 
ENABLEMENUITEM fae Bite, mWin20  mWind0  mWindl 
Purpose Changes a menu item to/from enabled and cael oe ae 
Syntax WORD EnableMenultem(HMENU hMenu, WORD wiDEnableltem, WORD wEnable); . 


Description Menu items are normally enabled, meaning that selecting a menu item causes a WM_COMMAND— 
message to be sent to the window's message function. Menu items can be disabled, stopping the 
" messages from being sent. Normally disabled menu items are shown in gray text so that the user 
‘can easily see which commands function. 


Uses Some menu actions may not be possible under all situations in a program. For example, it should 
not be possible to paste data if no data has been cut or copied into the clipboard. In these situa- 
tions, it is best to disable and gray the menu items that have no function, so that the user intu- 
itively knows that certain actions are not possible. 


Returns WORD holding the previous state of the menu item (MF_GRAYED, Say. —] is returned if the 
menu or menu item does not exist. 

See Also GetMenuState(), ModifyMenu(), GetMenuQ) 

Parameters 

hMenu ' HMENU: A handle to the menu. Use GetMenu() to retrieve a window's menu. 

wIDEnableltem WORD: The menu item number to change. 

wEnable ‘WORD: The action to take, and how wiDEnableltem is to be interpreted. The values shown in 


. Table 4-7 can be combined with the C language binary OR (I) operator. 
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“Meaning 


MF_BYCOMMAND The niDEnableltem value is the menu item ID value. 


MF_BYPOSITION The niDEnableitem value is interpreted relative sequential numbering of the menu items: 0 is the first item, 
1 the second, etc. 


MF_DISABLED The menu item is disabled. 
MF_ENABLED The menu item is enabled (and not grayed). 
MF_GRAYED The menu item is grayed. 


Table 4-7. EnableMenultem() Flags. 


Related Messages WM_COMMAND 


Example This example’s window has a menu with one drop-down popup menu. The second item on the 
drop-down menu (IDM_OPT1) alternately disables and enables the third menu item 
(IDM_OPT2). When disabled, the menu item is also grayed. Here is the resource file. Note that 
the menu items all start enabled, the default condition. 

/* genmenu.rc */ 


#include <windows.h> 
Hinclude "genmenu.h" 


genmenu ICON -generic.ico 
genmenu ; MENU 
BEGIN 
POPUP "&First Menu" 
BEGIN 
MENUITEM “&Top Item", IDM_TOP1 
MENUITEM “&Disable 2nd", ' IDM_OPT1 
MENUITEM SEPARATOR / 
MENUITEM "&2nd Option", -IDM_OPT2 
END . 
MENUITEM “&Quit", IDM_QUIT 


END 


The following code is the first part of the WndProc() function. GetMenuState() is used to . 
find out whether the IDM_OPT2 menu item is currently enabled. If so, EnableMenultem() is 
used to disable it. Also, the IDM_OPT1 menu item text is changed with ModifyMenu() to switch 
between “Enable 2nd” and “Disable 2nd” as appropriate. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
: a . 


_HMENU hMenu ; 
_ WORD wStatus ; 


switch (iMessage) ; /* process windows messages */ 
{ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_OPT1: /* Toggle menu item enable/disable */ 
. hMenu = GetMenu (hWnd) ; 
wStatus = GetMenuState Antenss IDM_OPT2, 
MF_BYCOMMAND) ; 
Gf CwStatus == MF ENABLED) 
{ 

EnabLeMenultem ChMenu, IDM_OPT2, 
MF_DISABLED | MF_GRAYED | 
MF_BYCOMMAND) ; 

ModifyMenu (hMenu, IDM_OPT1, 
MF_.BYCOMMAND | MF_STRING, 
IDM_OPT1, "Enable 2nd") ; 
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else 
{ 
EnableMenultem (hMenu, IDM_OPT2, 
MF_ENABLED | MF_BYCOMMAND) ; 
ModifyMenu (hMenud, IDM_OPT1, 
MF_BYCOMMAND | MF_STRING, 
IDM_OPT1, "Disable 2nd") ; 
} ‘ 
break ; 
[Other program lines] 
GeTMENU BWin2.0 mWin3.0 mWin3.1 
Purpose Retrieves a handle to a window's menu. 
Syntax | HMENU GetMenu(HWND hWnd); . 
Uses Used prior to modifying or assiroymne © the menu. This function will not return a valid handle for 
child windows with menus. 
* Returns es HMENU, a handle to the menu. NULL if the window does not have a menu. 
See Also SetMenu(), AppendMenu(), DeleteMenu(), Deen: InsertMenu(), ModifyMenu(), 
RemoveMenu, 
Parameters 
- hWnd : HWND: A handle to the window that has the menu. 
Example This example deletes the IDM_TOP1 menu item when it is selected. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : é 


HMENU hMenu ; 
switch (iMessage) /* process windows messages */ 
{ . 7 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_TOP1: /* Delete a menu item */ 
hMenu = GetMenu ChWnd) ; 
DeleteMenu (hMenu, IDM_TOP1, MF_BYCOMMAND) ; 
DrawMenuBar ChWnd) ; 
break ; 
[Other program lines] 
GETMENUCHECKMARKDIMENSIONS BWin2.0° mWin30 wWin3.1 
Purpose Retrieves the size and width of the bitmap used to create checkmarks next to menu items. 
Syntax DWORD GetMenuCheckMarkDimensions(void); 
Description Windows uses a default checkmark bitmap to check menu items. This can be replaced with cus- 


tom bitmaps using the SetMenultemBitmaps() function. GetMenuCheckMarkDimensions() is 
used to find the size of the bitmap to use for custom checkmarks. 


Uses Custom checkmarks can dress up an application program, with little penalty in memory con- 
. sumption. As soon as the new bitmap is assigned to the menu item, the CheckMenultem() func- 
tion will automatically use this bitmap when checking or unchecking an item. 


Returns © DWORD, the HIWORD contains the bitmap height in pixels, the LOWORD contains the bimap 
- width in pixels. - 


See Also SetMenultemBitmaps(), CheckMenultem() 
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Parameters None (void). 


Example In this example, a bitmap called “pen” is to be used as the checkmark for the IDM eh menu 
item. As the program does not know in advance how big the menu checkmarks are going to be 
(this depends on the video display resolution), the bitmap must be sized to fit the dimensions 
found when the program starts running. Size the bitmap by copying the bitmap from one device 
context to another using the StretchBit() function. The resource .RC file loads the “pen” bitmap. 


/* genmenu.rc */ 
finclude <windows.h> 


finclude “genmenu.h" : 
genmenu ICON generic.ico 


pen BITMAP smallpen.bmp 
genmenu MENU 
BEGIN ey 
POPUP "&First Menu” | 
' BEGIN i 
MENUITEM “&Top Item", : IDM_TOP1 
MENUITEM “&Check Me!", IDM_OPT1 
MENUITEM SEPARATOR 
MENUITEM “&2nd Option", : IDM_OPT2 
END 
RENUITER “eauit", : IDM_QUIT 


The new menu item bitmap is sized and loaded when the WM_CREATE message is received 
at program startup. In this simple example, the IDM_OPT1 menu item just toggles between being 
checked with the “pen” bitmap, and being unchecked. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG \Param) 
{ ; 


HAENU hMenu ; 
DWORD duCheckSize ; _ 
HDC: hdc, hSourcedC, hDestDC ; 
static HBITMAP hPenBitmap ; 
HBITMAP © hMemBitmap ; 
BITMAP bm ; 
int nBx, nBy ; 
-  BOOoL bChecked ; 
switch CiMessage) _/* process windows messages */ 


case WM_CREATE: 
/* find out how big. the checkmarks are */ 
hMenu = GetMenu (hWnd) ; 
dwCheckSize = GetMenuCheckMarkDimensions ©; 
nBx = LOWORD (dwCheckSize) ; 
nBy = HIWORD (dwCheckSize) ;... 
. ; Gl load a Btenap into a device context a] 
hdDC = GetDC ChWnd) ; 
hSourceDC = Crentecoanatiblabe hbo) ; 
hPenBitmap = LoadBitmap (ghInstance, Sen") ; ; 
SelectObject (hSourceDC, hPenBitmap) ; 
GetObject ChPenBitmap, sizeof (BITMAP), (LPSTR) gbm) ; 

~- /* create a: second DC for seated bitmap */ 

hDestDC = CreateCompatibleDC (hDC) ; 
——~ hMemBitmap = Ceeatecompatiblelitaap ChDestDC, Bx, nBy) ; 
on teceonseck: ChDestDC, hMemBitmap) ; 
; /* fit the bitmap into the menu sized DC */ 

Stretchalt ChDestDCc, 0, 0, nBx, nBy, hSourcedC,, 0, 0, 

bm. baWidth, bm. baleight, SRCCOPY) ; 

Moat, se . #* attach the sized bitmap to the menu item */ 

SetMenultemBitmaps ChMenu, IDM_OPT1, MF_ —BYCOMMAND, NULL, 

RNSRELTREP? 2 

-/* release unneeded memory consumers */ 
NN. 
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ReleaseDC (hWnd, hDC) ; 
DeleteDC ChSourceDC) ; 
DeleteDC ChDestDC) ; 
DeleteObject ChPenBitmap) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
‘case IDM_OPT1: . Toggle menu item checked/unchecked a/ 


hMenu = GetMenu ChWnd) ; 
bChecked = GetMenuState ChMenu, I0M_OPT1, 
MF_BYCOMMAND) ; 
4f (bChecked & MF_CHECKED) 
CheckMenultem (hMenu, IDM_OPT1, 
: “<M F_BYCOMMAND | MF_UNCHECKED) ; 
else : 
CheckMenultem (hMenu, IDM_OPT1, 
' MF_LBYCOMMAND | MF_CHECKED) ; 
break ; ; 
case IDM_QUIT: 
DestroyWindow ChWnd) ; 
break ; 
i} 
break ; 
case WH_| DESTROY: /* stop application af 
DeleteObject (hPenBitmap) ; 
. PostQuitMessage (0) ; 
break ; ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


>: 
return (OL) ; 


} . 
GetMenuITEMCouNT : . sg Win20)mWin3.0) m@Win3.1 
Purpose Gets the number of menu items in a menu. 
Syntax — WORD GetMenultemCount(HMENU hMenu); 
Description GetMenultemCount() counts the number of menu items, This includes the top-level heading of 
any popup menus, but does not include the popup items themselves. 
Uses Used to find out how many menu items there are, prior to dees data on the menu items such 
| as their ID numbers, strings, etc. 
~~. Returns WORD, the number of menu items. Returns —1 on error. 
See Also GetMenu(), GetMenultemID(), GetMenuState(), GetMenuString() 
Parameters | os | 
- hMenu HMENU: A handle to the menu. Use GetMenu() to find a win- Aerie tiie a 
PevstMenu Que 
dow’s menu handle. eee on 
Example — This example uses several menu functions to determine the | 2 Unchecked. tour iia 


number, IDs, status, and menu strings associated with the 
program’s main menu. After execution of the first popup menu _ Figute 4-5. GetMenu- 
selection under “First Menu,” the window looks like Figure 4-5.  TtemCount(, ) Example. 

Note that the string “First Menu” is a popup menu name, — 
so it does not have a selectable ID value (shown as —1). The “Quit” option is selectable, with an ID 
value of 2. The popup menu items are not displayed and must be separately examired using - 
GetSubMenu(). Also note that the ampersand characters used to define the Gun-key combina- 
tions are extracted with GetMenuString(). 


127 


WINDOWS API BIBLE 


&> The Resource File 


/* genmenu.rc */ 


#include <windows.h> . 


#include “genmenu.h" 


genmenu ICON generic.ico 
genmenu MENU 
BEGIN 
POPUP "&First. Menu" 
BEGI : 
MENUITEM "&Display Items", IDM_TOP1 
MENUITEM "&ist Option”, IDM_OPTi 
MENUITEM SEPARATOR 
MENUITEM "&2nd Option", IDM_OPT2 
END , 
MENUITEM “&Quit", IDM_QUIT 


END . > 


> The Top of the WndProc() Function 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HMENU 
HDC 
char 
int 


hMenu ; 
hdc ; 


cBuf. £128), cNumBuf C10] ; 
4, nItems, nValue, nChecked, nChars ; 


switch CiMessage) 
{ 


“case Wa_COMMAND: 


“switch (wParam) 


case IDM_TOP1: 


/* process windows messages */ 


/* process menu items */ 
' 


/* Show menu item attributes */ 


hDC = GetDC ChWnd) ; 


hMenu = 


GetMenu ChWnd) ; 


nitems = GetMenultemCount Chenu) ; 
TextOut a 0, 0, “ID Checked String", 19) 5 


for (i =0 ; i <nitems ; oot? 
{ a 
nValue = GetMenultemID Chenu, 4)-3 
nChecked = GetMenuState (hMenu, i, 
‘ME_| BYPOSITION | MF_CHECKED) ; 
nChars = GetMenuString Conenu, i, cBut, 127, 
MF_BYPOSITION) ; 
; _itoa (nValue, cNumBuf, 10) is 
TextOut ChDC, 10, 15 + €i * 15), cNumBuf, 
strlen (cNumBuf)) ; 
if (nChecked == MF_CHECKED) 
' TextOut ChDC, 30, 15 + “ * a2 
"Checked", 7) 3 
else 
TextOut (hDC, 30, 15 + (i * 15), 
“Unchecked", 9) ; 
TextOut ChdC, 150, 15 + Ci * 15), cBuf, nChars). ; 
, ; 
ReleaseDC mee hoc) ; 
‘break a 
{Other program lines] 
GetMenvltemID : Win2.0  mWin3.0 wmWin3.) 
Purpose | Retrieves the ID value associated with a menu item. , 
Syntax - WORD GetMenultemID(HMENU hMenw, int nPos); 


Description The menu ID values are associated with each item when the menu is defined, either in the re- 
source .RC file or when the menu items are added during program execution with the 
AppendMenu() and InsertMenu() functions. 
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Uses ID values remain constant, even as other menu items are added and deleted. Retrieving the menu 
item IDs can be useful in programs which allow the user to add and subtract custom menu items 
such as macro names. — 

Returns — WORD, the ID value for the menu item at position Pos. —1 on error. 

See Also GetMenultemCount(), GetMenuState(), GetMenuString(). 

Parameters . 

hMenu HMENU: A handle to the menu. Use GetMenu() to retrieve a handle to a window’s menu. Use 
GetSubMenu() to retrieve a handle to a popup menu. 

Example See the previous example under the GetMenultemCount() function description. 

GETMENUSTATE . gWin2.0 s8Win30 mWin3t 

Purpose Finds the number of items in a menu or the status of an item. 

Syntax WORD GetMenuState(HMENU hMenu, WORD wID, WORD wFlags); 

Uses Most often used to determine if a menu item is checked, grayed, or disabled. 

Returns WORD. Returns —1 on error. If w/D identifies a pupup menu, the high-order byte contains the 


number of items in the popup menu. The low-order byte contains a combination of the flags 
shown in Table 4-8, logically ORed together. 


: . Meaning 

MF_CHECKED There is a checkmark next to the menu item. 

MF_DISABLED The menu item is disabled and cannot be selected. 

MF_ENABLED The menu item is enabled, so it can be selected. 

MF_GRAYED . The menu item text is grayed and disabled so that it cannot be selected. 

MF_MENUBARBREAK In popup menus, it separates a new column of items and displays a seperate bar between 

- them. In normal menus, it starts a new line of menu items. 

MF_MENUBREAK In popup menus, it separates a new column of items. No separator bar is displayed. In normal 
menus, it breaks the menu into a new liné of menu items (two rows of menu items at the 
window’s top). 

MF_SEPARATOR A horizontal line in the menu: 

MF_UNCHECKED No checkmark next to the menu item. 


Table 4-8. GetMenuState() Return Flags. 


See Also CheckMenultem(); GetMenu() 

Parameters | 

hMenu HMENU: A handle to the menu. Use GetMenu() to obtain a window’s menu. 
wID WORD: The menu item ID value. 

wFlags WORD: Specifies how the wD is to be interpreted, as shown in Table 4-9. 


MF_BYCOMMAND The wiD value is the menu item ID value. 


MF_BYPOSITION The wiD value is interpreted relative sequential numbering of existing menu items: 0 is the first 
item, 1 the second, etc. 


Table 4-9. GetMenuState() wFlags Settings. 
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Example _ Here the menu item IDM_OPT! toggles between being checked and unchecked each time it is 
| _ selected. Note that GetMenuState() is used to find the current menu item status (checked or 
unchecked). 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HMENU hMenu ; 
BOOL bChecked ; 
switch (iMessage) /* process windows messages */ 
{ : 
case WM_COMMAND: /» process menu items */ 


switch: (wParam) 


case IDM_OPT1:. 
hMenu = GetMenu ChWnd) ; 
” bChecked = GetMenuState (hMenu, IDM_OPT1, 
_ ME_BYCOMMAND) ; 
if (bChecked & MF_CHECKED) 
' CheckMenuItem (hMenu, IDM_OPT1, 
\ MF_BYCOMMAND | MF_UNCHECKED) ; 

else : 

CheckMenultem (hMenu, IDM_OPT1, 

MF_BYCOMMAND | MF_CHECKED) ; 


: break ; 

[Other program lines] 

GETMENUSTRING BWin2.0 mWin3.0 mWin3.1 

Purpose Retrieves the label displayed in a menu item. a | . 

Syntax int GetMenuString(HMENU hMenu*WORD wIDitem, LPSTR lpString, int nMaxCount, WORD 
wFlag); . 

Description The menu item’s string, including the ampersand (&) character used to specify the accelerator 

. key, is retrieved into a character buffer. 
Uses Handy in programs that allow the user to add and subtract menu items for user-defined functions 

such as macros. 

Returns int, the number of characters retrieved. 

See Also GetMenu(), GetMenultemCount(), GetMenultemID(), GetMenuState(), GetSubMenu() 

Parameters : 

hMenu HMENU: A handle to the menu. Use GetMenu() to obtain a window's menu. 

wlDitem WORD: The menu item ID value. . 

lpString LPSTRING: A pointer to the character buffer that will hold the menu item string. 

nMaxCount int: The maximum number of characters to write to the buffer. Use this parameter to avoid 
writing beyond the buffer’s end. 

wFlags WORD: Specifies how the w/DJtem is to be interpreted, as shown in Table 4-10. 

Value - Meaning | ae “Dd 


MF_BYCOMMAND The n/Ditem value is the menu item ID value. 


MF_BYPOSITION The niDitem value is interpreted relative to the sequential numbering of existing menu items: Ois the first 
item, 1 the second, etc. 


Table 4-10. GetMenuString() wFlags Settings. 


Example See the example under the GetMenultemCount() function description. 
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GETSuBMENU 


Purpose 
Syntax 
Description 


Uses 
Returns 
See Also 
Parameters 


hMenu 
nPos 


Example 


mWin2.0 m8 Win3.0 m8 Win3.! 
Retrieves a handle to a popup menu. 
HMENU GetSubMenu(HMENU AMenu, int nPos); ; 
Ahandle to a popup menu can only be found after the handle to the main menu is located, usually 
with GetMenu(). When the popup menu handle is obtained, all of the functions that allow read- 
ing and changing menu items can be applied to the popup menu. 
in programs that change the elements of popup menus. 
HMENU, a handle to the popup menu. Returns NULL on error, such as nPos not referring to a 
popup menu. 
GetMenu(), GetMenultemCount(), GetMenultemID(), GetMenuitemState(), GetMenultem- 
String(), AppendMenu(), ModifyMenu() 


_HMENU: A handle to the parent menu of the popup menu. 


int: The position of the popup menu in the main menu: 0 for the first, 1 for the second, etc. 
Because popup menus do not have ID values associated with them, it is not possible to retrieve 
the menu handle based on an ID. 

Here the program examines the first popup menu, and shows 
each of the popup menu items on the screen. Note that the 
third item in the popup menu is a separator bar. This has an ID 
of 0. The MF_SEPARATOR status for this item could have been 
detected using the GetMenuState() function. Figure 4-6 illus- 


Fr : ovr -genmenu : {- [= 
ID Checked String 
1 Unchecked &Display Items 
3 Unchecked &lst Option 

O Unchecked 

4 Unchecked &2nd Option 


trates the example. 
_ The following code represents the resource .RC file that Figure 4-6. GetSubMenu() 
defines the menu structure, including the popup menu. Example. 


/*®* genmenu.rc */ 
#include <windows.h> 
#include “genmenu.h” 


genmenu ICON generic.ico 
genmenu MENU 
BEGIN 
POPUP “&First Menu” 
BEGIN 
MENUITEM “&Display Items", IDM_TOP1 
MENULTEM “&1st Option", I1DM_OPT1 
MENUITEM. SEPARATOR 
MENUITEM “&2nd Option", 5 IDM_OPT2 
END : 
MENUITEM “&Quit", IDM_QUIT 
END 


The following code represents the top of the WinMain() function. Note that the submenu is 
retrieved after the main menu is found using GetMenu(). 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


{ 
HMENU hMenu, hSubMenu ; 
HDC hdc ; 
char cBuf C128], cNumBuf £10] ; 
int i, nItems, nValue, nChecked, nChars ; : 
switch (iMessage) : /*® process windows messages */ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) . : 
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C , 
case IDM_TOP1: /* Show menu item attributes */ 
hDC = GetDC (hwnd) Py : Do ; 
hMenu = GetMenu (hWnd) ; 
hSubMenu = GetSuhMenu Chnenus 0); 
nItems = GetMenuItemCount (hSubMenu) ; 
TextOut (hDC, 0, 0, "ID Checked String", 19) ; 
for (4 = 0; i <nItems ; i++) 
£ : : = 
nValue = GetMenultemID (hSubMenu, i) : 
nChecked = GetMenuState (hSubMenu, i, 
MF_BYPOSITION | MF_CHECKED) ; 
nChars = GetMenuString (hSubMenu, i, 
cBuf, 127, MF_BYPOSITION) ; 
jtoa (nValue, cNumBuf, 10) ; 
TextOut (hDC, 10, 15 + Ci * 15), cNumBuf, 
strlen CcNumBut)) ; 
if (nChecked == MF_CHECKED) 
TextOut (hDC, 30, 15 + €i * 15), 
: "Checked", 7) ; 
else 
fextOut (hDC, 30, 15 + (7 * 15), 
. "Unchecked", 9) ; 
YextOut (hdc, 150, 15 + (i * 15), 
“ -  ¢Buf, nChars) ; 
ReleaseDC (hWnd, hDC) ; 
break. ; 
[Other program lines] « 
GETSYSTEMMENU BWin2.0 8 Win3.0 -mWin3t 
‘Purpose =—S™—séRReetrieves a handle to the system menu. 
Syntax HMENU GetSystemMenu(HWND hWnd, BOOL bRevert); 
Description The system menu is the popup menu that is displayed when you click the button at the top left 


corner of the program’s main window. The system menu generates WM_SYSCOMMAND mes- 
sages, not WM_COMMAND messages. When a menu item on the system menu is activated, the 
WM_SYSCOMMAND messages have the wParam parameter set as shown in Table 4-11. 


System Menu Item Sends WM_SYSCOMMAND with wParam Set To Xx 
Restore SC_RESTORE , 
Move SC_MOVE 

Size “SC.SZE 

Minimize SC_MINIMUM 

Maximize SC_MAXIMUM 

Close . ». SC_CLOSE 

Switch To ~ SC_TASKLIST 


Table 4] d. WM_SYSCOMMAND Message wParam Values. / 


You can also modify and add to the system menu using all of the menu modification com- 
mands, such as AppendMenu() and InsertMenu(). If you add menu items, their ID values should 
~. be below 0xF000 to avoid overlapping the definitions of the default ID values listed above. 


Uses Modifying the system menu is appropriate for small utility programs that may be able to avoid 
having a menu bar if a few commands are added to the ne syesent menu. 
Returns HMENUSa handle to the system menu. 
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See Also 


Parameters 
hWnd 


bRevert 


Related Messages 
Comments 


Example 


AppendMenu(), InsertMenu(), ModifyMenuQ) 


HWND: A handle to the window which contains the system menu. 


BOOL: If TRUE, the function destroys the current system menu and returns a handle to a new’ 
copy of the original system menu. If FALSE (zero), the function returns a handle to the current 
system menu, retaining any changes. 

WM_SYSCOMMAND, WM_INITMENU 


In processing the WM_SYSCOMMAND messages for the default system menu items, it is critical 
to pass the WM_SYSCOMMAND message on to the default window's message processing function 
DefWindowProc(). Otherwise the program will stop functioning. The example shows this mes- 
sage pass-through. _ 

Here a single menu item is added to the bottom of the system menu, called “Added Item.” When 
this item is clicked, the WM_SYSCOMMAND message is caught and some text written to the 
window’s client area. Note how the message logic passes any other WM_SYSCOMMAND message 
straight through to DefWindowProc(), to avoid ‘han ging the program. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG tParam) 


{ ’ 
HMENU hSysMenu ; 
HOC hoc ; 
switch CiMessage) /* process windows messages */ 
t é 
case WM_CREATE: 
hSysMenu = GetSystemMenu (hWnd, O) ; 
AppendMenu ChSysMenu, MF_STRING, 10M _SYSTYPE, “added Item") ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostaQuitMessage (0) ; 
break ; 
case WM_SYSCOMMAND: 
if (wParam == IDM_SYSTYPE)/* added system menu item */ 
{ 
hDC = GetDC (hWnd) ‘i 
TextOut (hDC, 10, 
“The new systen menu item was hit.” 33) ; 
ReleaseDC ends hDC) ; 
‘return (0) ; ; 
}  * no break statement here */ 
default: ‘ /* default windows message processing */ 
return DefWindowPrac (hWnd, iMessage, wParam, lParam) ; 
. 3 ; ; 
-return COL) ; 
} 
HiireEMENvITEM | mWin2.0 wWin3.0 Win 3.1 
Purpose Highlights a top-level menu item. a4 
Syntax BOOL HiliteMenultem(HWND hWnd, HMENU hMenu, WORD wlDHiliteltem, WORD wHilite); 
Description Normally, the mouse and default keyboard accelerator key’s automatic actions take care of high- 


_ lighting top-level menu items. If you need to do this directly, you can use HiliteMenultem(). 
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Uses Seldom used. Can be used to provide additional saa functionality for menu selections (see 
example). , 

Returns BOOL. TRUE if the item was highlighted, FALSE on error. 

See Also GheeiMemiltend) EnableMenultem() 

Parameters 

hWnd HWND: A handle to the program’ 's window. 

hMenu HMENU: A handle to the program’s menu. Use GetMenu() to retrieve this handle. 

wlDHiliteltem WORD: The menu item number to change. Only top-level menu items may be changed. _ 

wHilite WORD: Flags to set how the w/DHiliteltem parameter is interpreted and whether to highlight or - 


unhighlight the menu item. Combine two of the values in Table 4-12 with the C language OR 
operator (I). 


: _ Meaning 
MF_BYCOMMAND The niDHiliteltem value is the menu item ID value. 
MF_BYPOSITION The niDHiliteltem value is interpreted relative to the sequential numbering of existing menu 
items: O is the first item, 1 the second, etc. 

MF_HILITE Highlight the menuitem. 

MF_UNHILITE Remove highlighting from the menu item. 
Table 4-12. HiliteMenultem() Flags. . 
Example - This example implements a simple keyboard interface for.a two-item menu. If the user hits the 


left or right arrow keys, one of the menu items is highlighted. Hitting the return key selects the 
highlighted menu item. The only two actions in this case are to display a message box or to exit 


the program. 
© The Resource .RC file 
/* genmenu.rc jim conger 1991 */ 


#include <windows.h> 
#include “genmenu.h" 


genmenu. ICON generic.ico 
' genmenu MENU 
BEGIN 
MENUITEM "&1st Option", IDM_TOP1 
MENUITEM "&Quit",  . IDM_QUIT 
END 


The following code represents the WndProc() function. Note that the return key action is 
implemented by sending the same message that would have been received ifa mouse click had 
selected the item (WM_COMMAND). This allows the same logic to perform the functions, regard- 
less if a mouse or keyboard is used. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{. ; 


HMENU  hMenu ; 
static int nSide =O; 
switch (iMessage) /* process windows messages */ . 
case WM_COMMAND: /* process menu items */ 
Suneeh (wParam): 
t .. 


case IDM | TOP1: 
MessageBox (hwnd, "First menu item was hit", 
“Message”, MB_OK) ; 
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} 


break ; 


case IDM_QUIT: 
DestroyWindow ChWnd) ; 
break ; 

} 

break ; 

case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
case WM_KEYDOWN: 

switch (wParam) 

{ 

case VK_LEFT: /* Left arrow key, so hilite "top1" */ 
hMenu = GetMenuChWnd) ; 
HiliteMenultem (hWnd, hMenu, 0, 

MF_BYPOSITION | MF_HILITE) ; 
HiliteMenultem ChWnd, hMenu, 1, 
MF_BYPOSITION | MF_UNHILITE) ; 

DrawMenuBar ChWnd) ; 
nSide =0; 
break ; 


case VK_RIGHT: /* right: arrow key, so hilite "Quit" */ 
hMenu = GetMenuChWnd) ; 
HiliteMenultem (hWnd, hMenu, 0, 
MF_BYPOSITION | MF_UNHILITE) ; 
HiliteMenultem (hWnd, hMenu, 1, . 
MF_BYPOSITION | MF_HILITE) ; 
DrawMenuBar (hWnd) ; 
nSide =1; 
break ; 
case VK_RETURN: /* simulate mouse select of menu item */ 
if (nSide) 
SendMessage (hWnd, WM_COMMAND, IDM_QUIT, OL) ; 
else 
SendMessage (hWnd, WM_COMMAND, IDM_TOP1, OL) ; 
} 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


} 


INnSERTMENU 


Purpose 
Syntax 


Description 


Uses 
Returns 
See Also 


Parameters 
hMenu 


nPosition 


OWin2.0 Wins. mw Win3.l 
Inserts a new menu item into an existing menu. 


BOOL InsertMenu(HMENU hifenu, WORD nPosition, WORD wFlags, WORD wiDNewltem, 
LPSTR lpNewltem); 


Adds a new item into any location within a menu. This is more useful than AppendMenu(), which 
only adds items.£o the end of the menu. 


Ideal for adding bitmap menu items 
BOOL. TRUE if the item was successfully added, FALSE if not. 
AppendMenu(), ChangeMenu(), CreateMenu(), DrawMenuBar() 


HMENU: A handle to the menu being changed. Use GetMenu() to retrieve a window's menu 
handle. 


WORD: The menu item number in front of which the new item will be inserted. The wFlags 


paramefér will either contain the MF _BYPOSITION or MF_BYCOMMAND flag, specifying how 


the nPosition value is to be one 
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wFlags 


\ 


WORD: Specifies how the nPosition parameter is to be interpreted in positioning the new menu 
item. Also sets the status of the new menu item. These values can be combined using the © 
language binary OR operator (!) with any of the following menu item control flags, as shown in 
Table 4-13. 


MF_BITMAP 
MF_BYCOMMAND 
MF_BYPOSITION 
MF_CHECKED 
MF_DISABLED 


MF_ENABLED 
MF_GRAYED 


MF_MENUBARBREAK 


_ MF_MENUBREAK 


MF_OWNERREDRAW 


MF_POPUP 
MF_SEPARATOR 


MF_STRING 
MF_UNCHECKED 


Meaning 


The menu item will be a bitmap. The low-order word i the loNewltem parameter should 
contain a handle to the bitmap. 


The nPosition vaiue is interpreted as a menu item D value. The new item is inserted before the 
exiting one. 


The nPosition value is interpreted relative to the sequential numbering of existing menu items: 0 
is the first item, 1 the second, etc. The new item is inserted before the exiting one. Use an 
nPosition value of -1 for the end of the menu. 


Places a checkmark next to the menu item. 

Makes it impossible to select the menu item. Does not gray the menu item. . 
Makes it possible to select the menu item. This is the default. 

Grays the menu item text and disables the menu item so that it cannot be selected. 


In popup menus, it separates a new column of items and displays a separator bar Dewees) 
them. In normal menus, it starts a new line of menu items. 


In popup menus, it separates a new column of items. No separator bar is displayed. In norma! 
menus, it breaks the menu into a new line of menu items (two rows of menu items at the 
window's top). 


Specifies that the parent window is to paint the menu item each time it is needed. This is not 
possible for the top menu line, but can be done for drop-down and popup menu items. The 
parent window will receive WM_MEASUREITEM and WM_DRAWITEM messages to update the — 
drawing area. 


Specifies a popup menu. The wiDNewltem parameter will be a handle to the popup menu. 


_Draws a horizontal line in the menu. This line cannot be selected, checked, enabled, or grayed. 
The foNewltem and wiDNewltem parameters are ignored. 


Specifies that the new item is a character string. loNewltem points to the string. 
Does not place a checkmark next to the menu item. This is the default. 


Table 4-13. InsertMenu() wFlags Values. 


wlDNewltem 


lpNewltem 


WORD: Specifies the ID value for the menu item. If wFlags i is set to MF_POPUP, wlDNewltem is 
the menu handle of the new popup menu. 


LPSTR: Points to the contents of the new menu item. The type of data depends on the wFlags 
setting, as shown in Table 4-14. 


ipNewitem 


MF_STRING 
MF. BITMAP — 
_ MF_OWNERDRAW 


Long pointer to a character string. 


’ Abitmap handle. The bitmap handle is stored in the low-order word of joNewitem. 


You specify to what 32-bit value the joNewitem points. Windows will send WVM_MEASUREITEM and 
WM_DRAWITEM messages to the window's message processing function when the menu item needs to 
be redrawn. See the example owner-drawn menu program in the introductio to this chapter. 


Table 4-14. InsertMenu() Data Types. 
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_ Related Messages WM_MEASUREITEM, WM_DRAWITEM 
Example This example adds a bitmap to the window's menu, right before the WM_TOP1 menu item. The 
new menu item has the ID value of ID_PEN. . 


> Header File 


/*® genmenu.h */ 


Hdefine IDM_TOP1 1. /* menu item id values */ 
Hdefine IDM_QUIT 2 
#define IDM_PEN 3° 
'Adefine IOM_HELP 8 
/* global variables */ 
int ghInstance ; 
char gszAppName CJ = “genmenu" ; 


/* function prototypes */ 
Long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 


C> Resource File 


/*®* genmenu.rc x/ 
#include <windows.h: 
#include “genmenu.h" 


genmenu ICON generic.ico 

menubitmap BITMAP pen.bmp 

genmenu MENU 

BEGIN 
POPUP "&First Menu” 
BEGIN . 
, MENUITEM “&Top Item", IDM_TOP1 
END ; 
MENUITEM "&Quit", IDM_QUIT 


MENUITEM "\a&Help", IDM_HELP, HELP 
END 


© Part of the Program File 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


. HMENU hMenu ; 
HBITMAP hBitmap ; 
switch CiMessage) /* process windows messages */ 
{ . ; 


case WM_CREATE: - 
hMenu = GetMenu (hWnd) ; 
hBitmap = LoadBitmap (ghInstance, “menubitmap") ; 
InsertMenu (hMenu, IDM_TOPi1, MF_BITMAP | MF_BYCOMMAND, 
IDM_PEN, C(CLPSTR) (LONG) hBitmap) ; 


break ; 
[Other program lines] © 
LoapMENu _ . wWin20 mWin3.0 Wind 
Purpose Retrieves a handle to a menu defined in the resource .RC file. 
Syntax ~~ HMENU LoadMenu(HANDLE hJnstance, LPSTR pMenuNa:ne); 
Uses Used in the WinMain() function to load the program’s main menu. Can be used i in the body ofa 
program to load new menus to change menus as the program operates. 
Returns _ HMENU, a handle to the menu. NULL if no menu was found. 
See Also SetMenu(), DestroyMenu() 
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Parameters ; 

hInstance HANDLE: The handle of the program instance. . . 

lpMenuName LPSTR: A pointer to a string containing the menu name. The menu name is defined in the re- 

source .RC file as the first word in the MENU statement. 

Example See the example under the DestroyMenu() function description. 

-LoapMENuINDIRECT , OWin2.0 mWin30 mWin3l 
Purpose Loads a new menu, defined in a memory block. . 
Syntax . HMENU LoadMenulndirect (LPSTR /pMenuTemplate), . 

Description This function reads a menu definition in a memory block and returns a handle to the menu cre- 
ated. The menu can then be attached to a window with SetMenu(). This function is used inter- 
nally by Windows, but can be called directly if you take the trouble to create the menu definition 
template. 

Uses Provides an alternative to the normal menu creation and modification functions. 

Returns HMENU, a handle to the menu created. Returns NULL on error. 

See Also LoadMenu(), ModifyMenu(), AppendMenu(), DrawMenuBar() 

Parameters 


lpMenuTemplate LPSTR: A pointer to a memory block containing the menu definition. The format of the memory 
block must start with a MENUITEMTEMPLATEHEADER structure, followed by one or more 
MENUITEMTEMPLATE structures defining each menuitem. — . 
The MENUITEMTEMPLATEHEADER structure is defined in WINDOWS.H as follows: 


typedef struct 
{ 


WORD versionNumber; /* set to 0 */ 
WORD offset; /* byte offset to first menuitem */ 
} MENUITEMTEMPLATEHEADER; 

The versionNumber is a placeholder for future updates to Windows. For now, set this value 
to zero. The offset is the number of bytes from the end of the header to the first 
MENUITEMTEMPLATE data. This is normally zero, assuming that the menu item data follows 

_ immediately in memory. Each menu item is defined ina MENUITEMTEMPLATE data structure. 
_ This is a bit difficult to work with for two reasons. One is that the miJD field is part of the struc- 
ture for all template types except MF_POPUP. In that case it is omitted. The other problem is 
a ' that the mtString is variable length. The end of the string is detected by the ending zero byte. 


typedef struct ; - 
€ 


WORD mtOption; /* MF_CHECKED, MF_END, etc. */ 
WORE mtID; /* jtem ID - not for MF_POPUP */ 
char mtString[1]; _ /* start of menu item string */ 


} MENUITEMTEMPLATE; 


The mtOption element can be a combination of the flags in Table 4-15, combined witit the C 
language binary OR operator (1). 


. Meaning EASE DA SEGA 
MF_CHECKED _ Places a checkmark next to the menu item. 
MF_END i , Specifies the end of a popup menu or static menu. 
MF_GRAYED . Grays the menu item text and disables the menu item so that it cannot be selected. 
MF_HELP . The menu item has a vertical bar to. the left, 
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MF_MENUBARBREAK . In popup menus, it separates a new column of items and displays a separator bar between 
them. In normal menus, it starts a new line of menu items. 

MF_MENUBREAK In popup menus, it separates a new column of items. No separator bar is displayed. In normal 
menus, it breaks the menu into a new line of menu items (two rows of menu items af the 
window's top). 

MF_OWNERREDRAW _ Specifies that the parent window is to paint the menu item each time it is needed. This is not 


possible for the top menu line, but can be done for'drop-down and popup menu items. The 
parent window will receive WM_MEASUREITEM and My | DRAWITEM messages to update the 


drawing area. 
MF_POPUP Specifies a popup menu. The mtiD element of the sieieierenetate structure does not 
, exist for this type. 
Table 4-15. MENUITEMTEMPLATE mtOption Flags. 
Example — This example creates a new menu, as shown in Figure 4-7, “generic : [= 


when the WM_CREATE message is processed. The menu is 
defined in a global memory block. The AppendMemory() func- 
tion at the bottom of the listing is used to simplify dealing with 
the variable-length fields used to define menus. It adds con- 
secutive chunks of data to the end of a memory block. 


Popup Quit 


First 
Second 


Figure 4-7. LoadMenu- 


; !ndirect() Example. 
® Header File «) , 


/* generic.h */ 
Hdefine IDM_FIRST 


#define IDM_SECOND 
'Adefine IDM_QUIT 


WN = 


#define MAXMENULONS 20 
/* global variables */ 
int . ghInstance ; 
char gszAppName CJ = "generic" ; 
/* functien prototypes */ 
long FAR PASCAL WndProc (CHWND, unsigned, woRD, CONG) ; 
void AppendMemory (LPSTR LpDest, LPSTR LpSource,. int eres BOOL bReset) ; 


oS WndProc() and AppendMemory() C Functions 


‘tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ : 

HANDLE hMem ; 

LPSTR LpMem ; 

WORD wValue ; 

HMENU : hMenu ; 

switch (iMessage) . /*® process windows messages */ 

{ > 


_case WM_CREATE: 
hMem = GlobalAtloc (GMEM_FIXED | GMEM_ZEROINIT, 
sizeof (MENUITEMTEMPLATEHEADER) + 
6 * (sizeof (MENUITEMTEMPLATE) + MAXMENULONG)) ; 
LpMem = GlobalLock (hMem) ; 


wValue = Q ; 

AppendMemory Citgnen. (LPSTR) &wValue, sizeof (WORD), TRUE) ; 
wVvalue = 0 ; : 
AppendMemory (tpMem, (LPSTR) euvatues sizeof (WORD), FALSE) ; 


wValue = MF_| POPUP ; 
AppendMenory CupWens CLPSTR) &wValue, sizeof (WORD), FALSE) 
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AppendMemory (lpMem, 


wValue =O; | 

AppendMemory (lpMem, 
wValue = IDM_FIRST ; 
AppendMemory (tpMem, 
AppendMemory (lpMem, 


wValue = MF_END ; 

AppendMemory (lLpMem, 
wValue = IDM_SECOND ; 
AppendMemory (tpMem, 
AppendMemory ClpMem, 


wValue = MF_END ; 
AppendMemory (lpMem, 
wValue = IDM_QUIT ; 
AppendMemory (lpMem, 


AppendMemory (LpMem, 


“&Popup", 7, FALSE) ; 


CLPSTR) &wValue, sizeof 


(CLPSTR) &wValue, sizeof 
"First", 7, FALSE) ; 


CLPSTR) &wValue, sizeof 


CLPSTR) &wValue, sizeof 
"&Second", 8, FALSE) ; 


‘(LPSTR) &wValue, sizeof 


(LPSTR) &wValue, sizeof 
"BQuit", 6, FALSE) ; 


(WORD), 


(WORD), 


(WORD), 


(WORD), 


(WORD), 


(WORD), 


FALSE) 


FALSE) 


FALSE) 


FALSE) 


FALSE) 


FALSE) 


hMenu = LoadMenulIndirect (lpMem) ; 
SetMenu (hWnd, hMenu) ; 
GlobalFree (hMem) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ ; 
case IDM_FIRST: /* User hit the first menu item */ 
MessageBox (hWnd, "First Menu Item Works!", 
“Message”, MB_OK) ; 
break ; 
case IDM_SECOND: /* User hit the second menu item */ 
MessageBox (hWnd, "Second Menu Item Works!", 
"Message", MB_OK) ; 
break ; 
case IDM_QUIT: /* User hit the Quit menu item */ 
DestroyWindow (hWnd) ; 
break’; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 


} 
return (OL) ; 
} 


void AppendMemory C(LPSTR 
t 


return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 


N 


(pDest, LPSTR lpSource, int nBytes, BOOL bReset) 


int i; 
LPSTR lps, lLpd ; 
static int nLastEnd ; - 
lps LpSource ; 


lpd = LpDest ; 
if (bReset) 


nLastEnd = 0 >; 
else 
° { : 
for (i =0 5; i < nLastEnd ; i++) 
Lpdt+ ; 
} 
for (i = 0; i < nBytes ; i++) 
a 
' nLastEnd++ ; 
*lpd++ = *lps++t ; 
} 
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MopiryMEnu | ;  OWin2.0) mWin3.0 mWin3.l 
Purpose Changes the properties of a menu item. , 

Syntax . BOOL ModifyMenu(HMENU hMenu, WORD nPosition, WORD wFlags, WORD wlDNewltem, 
LPSTR [pNewltem); 

This is a powerful function for changing several attributes of a menu item at the same time. The 
status (grayed, checked, etc.), the menu item’s string or bitmap, and its ID value can all be 
changed in one function call. 


Description 


Uses Modifying a menu while the program operates. 

Returns BOOL. TRUE if the changes were made, FALSE on error. 

See Also CheckMenultem(), GetMenu(), DrawMenuBar() 

Parameters v.~ . 

hMenu HMENU: The handle to the menu. Use GetMenu() to retrieve a window's menu handle. 
nPosition WORD: The menu item to change. If the wFlags parameter contains MF_BYCOMMAND, 


nPosition refers to the menu item ID number. If wFlags contains MF_BYPOSITION, »Position 
refers to the absolute number of the menu item, 0 for the first, 1 for the second, etc. 

wFlags WORD: The attributes of the menu item after the changes. This parameter is made up from the 
list, in Table 4-16, using the C language binary OR (!) operator to combine effects. 


_ Meaning 


The menu item will be a bitmap. The low-order word of the joNewltem parameter should 
contain a handie to the bitmap. 


MF_BITMAP 


MF_BYCOMMAND 
MF_BYPOSITION 


MF_CHECKED 
MF_DiSABLED 
MF_ENABLED 
MF_GRAYED 
MF_MENUBARBREAK 


MF_MENUBREAK 


ME_OWNERREDRAW 
MF_POPUP 
ME_SEPARATOR 


MF_STRING 
MF_UNCHECKED 


The nPosition value is interpreted as a menu item ID value. This is the default. 


The Position value is interpreted relative to the sequential numbering of existing menu items: 0 
is the first item, 1 the second, etc. The new item is inserted before the exiting one. Use an 
Position value of -1 for the end of the menu. 


Places a checkmark next to the menu item. 

Makes it impossible to select the menu item. Does not gray the menu item. 

Makes it possible to select the menu item. This is the default. 

Grays the menu item text and disables the menu item so that it cannot be selected. 


In popup menus, it separates a new column of items and displays a separator bar between 
them. In normal menus, it starts a new line of menu items. 


In popup menus, it separates a new column of items. No separator bar is displayed. In normal 
menus, it breaks the menu into a new line of menu items (two rows of menu items at the 
window’s top). boy 

Specifies that the parent window is to paint the menu item each time it is needed. This is not 
possible for the top menu line, but can be done for drop-down and popup menu items. The ~ 
parent window will receive WM_MEASUREITEM and WM_DRAWITEM messages to update the 


. drawing area. 


Specifies a pcpup menu. The wiDNewltem parameter will be a handle to the popup menu. 


Draws a horizontal line in the menu. This line cannot be selected, checked, enabled, or grayed. 
The /oNewltem and wiDNewltem parameters are ignored. 


Specifies that the new item is a character string. /oNewitem points to the string. 
Does not place a checkmark next to the menu item. This is the default. 


Table 4-16. ModifyMenu( ) Flags. 
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wiDNewltem WORD: Specifies the ID of the menu item. IfwFlags is set to MF_POPUP, wIDNewltem specifies 
eG the menu handle for the popup menu. 


| lpNewltem LPSTR: Points to the contents of the changed menu item. The type of data depends on the wFlags 
. setting. (See Table 4-17.) 


~- IpNewltem: > . 
MF_STRING | Long pointer to a character string. 
MF_BITMAP A bitmap handle. The bitmap handle is stored in the low- sites word of joNewitem. 


MF_OWNERDRAW You specify to which 32-bit value the joNewitem points. Windows will send WM_MEASURE- ' 

; ITEM and WM_DRAWITEM messages to the window's message processing function when the 
menu item needs to be redrawn. The value in the /oNewltem parameter will end up passed to 
the window's function as an element of the structure pointed to by the /Param value. See the 
example owner-drawn menu program in the introduction to this chapter. 


Table 4-17, ModifyMenu() Data Types. 


Related Messages WM_MEASUREITEM, WM_DRAWITEM 


~ Example > This example uses ModifyMenu() to simultaneously change the IDM _oPT? menu item from 
grayed to normal text and change it’s character string to read “Now not Grayed.” 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HMENU hMenu ; 
switch CiMessage) /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 


case IDM_TOP1: 
hMenu = GetMenu ChWnd) ; 
ModifyMenu (ChMenu, IDM ‘opt2, 
MF_BYCOMMAND | MF_ENABLED | MF_STRING, 
IDM_OPT2, (LPSTR) “Now not Grayed") ; 


break ; 
[Other program lines 
RemoveMENU] OWin2.0 mWin3.0 mWin3.1 
Purpose - Removes a menu item from a main menu. 
Syntax BOOL RemoveMenu(HMENU hMenu, WORD nPosition, WORD wFlags); 
- Description = The menu item is removed from the main menu. Any popup menus are removed, but are not 


destroyed. Popups freed in this way can be reused. Be sure that all menus are either attached to 
the application’s main menu, or erased with DestroyMenu() bofore the application terminates to 
avoid leaving unattached menus in memory. 


Uses | Using RemoveMenu() is considerably simpler in these situations than DeleteMenu(), as 


RemoveMenu() allows the popup menu to be reattached, rather than rebuilt from scratch. Call 
GetSubMenu() to obtain the popup menu handle before using RemoveMenu(). 


Returns BOOL. TRUE if the menu item was removed, FALSE on error. 

See Also GetSubMenti(), DeleteMenu(), AppendMenu(), InsertMenu() 

Parameters . a | 
hMenu , HMENU: A handle to the menu. Use GetMenu() to obtain a handle to a window's menu. 
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nPosition 
' wFlags 
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WORD: The menu item to be removed. 
WORD: Sets how the »Postion value is interpreted (Refer to Table 4-18). 


Value Meaning : : x 


MF_BYCOMMAND 
MF_BYPOSITION 


The nPosition value is the menu item ID value. 


The nPosition value is interpreted relative to the sequential numbering of existing menu items: 0 
is the first item, 1 the second, etc. 


Table 4-18. RemoveMenu() Flags. ° 


Comments 
Example 


Use DrawMenuBar() after changing the menu items to force Windows to redraw the menu line. 


In this example, clicking the IDM_TOP1 menu item causes the first popup menu to be moved 
from the left of the menu bar to the far right. All of the popup menu items remain intact. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


{ 


HMENU 
static BOOL 


switch (iMessage) 


hMenu, hPopupMenu ; 
bMovedMenu = FALSE ; 


/* process windows messages */ 


case WM_COMMAND: 
switch (wParam) 


/* process menu items */ 


case IDM_TOP1: /* move first popup menu to menu end */ 

if (!bMovedMenu) 

{ 

hMenu = GetMenu (hWnd) ; 

hPopupMenu = GetSubMenu ChMenu, 0) ; 

RemoveMenu ChMenu, 0, MF_BYPOSITION) ; 

AppendMenu (hMenu, MF_POPUP, hPopupMenu, 
CLPSTR) "New Position") ; 

DrawMenuBar (hWnd) ; /* redraw menu bar */ 

bMovedMenu = TRUE ; /* don't try it twice */ 

% x 


} 
break ; 
[Other program lines] , 
SETMENU mWin2.0 mWin3.0 mWin31 
Purpose Attaches a menu to a window. 
Syntax BOOL SetMenu(HWND hWnd, HMENU hMenz); 
Description The menu attached can either be defined in a resource .RC file or created within the program 
with the CreateMenu() function. Any existing menu is removed. 
Uses Changing to a new menu, or removing a menu from the window. 
Returns BOOL. TRUE if the menu has been changed, FALSE otherwise. 
See Also CreateMenu(), DestroyMenu(), LoadMenu(), DrawMenuBar() 
Parameters - 
hWnd _HWND: A handle to the window which will change menus. 
hMenu HMENU: A handle to the menu to add. Use LoadMenu() to retrieve the handle to a menu defined 
in the resource .RC file. Set hMenu equal to NULL to remove the menu from a window without 
/ replacing it. . 
Example See the example under the DestroyMenu() function description. 
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SETMENUITEMBITMarPsS | 7 OWin20 wWin30 mWin31 


Purpose Replaces the default menu checkmark bitmap with a custom bitmap. 
Syntax . BOOL SetMenultemBitmaps(HMENU hMenu, WORD nPosition, WORD wFlags, HBITMAP 
hBitmapUnchecked, HBITMAP hBitmapChecked), 


Description Windows uses a default checkmark bitmap for checking menu items. This can be replaced with 

custom bitmaps using the SetMenultemBitmaps() function. The size of the checkmark bitmaps 

is dependant on the video resolution of the system the program is running on. GetMenu- 
CheckMarkDimensions() is used to find this size for scaling the bitmap to fit. 


. Uses Custom checkmarks can dress up an application program, with little penalty in memory con- 


sumption. When the new bitmap is assigned to the menu item, the CheckMenultem() function 
automatically will use this bitmap when checking or unchecking an item. 


Returns - BOOL. TRUE if the bitmap was set properly, FALSE on error. — 

See Also SetMenultemBitmaps(), CheckMenultem(), GetMenuCheckMarkDimensions() 

Parameters 

hMenu HMENU: A handle to a menu. Use GetMenu() to retrieve a window’s menu. 

nPosition WORD: The menu item number to change. 

wFlags WORD: Specifies whether nPosition refers to the menu item ID number or the sequential num- 


bering of menu items. This can be either of the values shown in Table 4-19. 


, --)” Meaning. - eae ABSA AS 
MF_BYCOMMAND The nPosition value is the menu item ID value. 
MF_BYPOSITION The nPosition value is interpreted relative sequential numbering of existing menu items: 0 is the 


‘first item, 1 the second, etc. 
Table 4-19, SetMenultemBitmaps() Flags. 


hBitmapUnchecked HBITMAP: A handle to the bitmap to display when the menu item is not checked. This can be 
NULL, leaving the side of the menu bar blank when unchecked (the normal case). oo 


hBitmapChecked BITMAP: A handle to the bitmap to display when the menu item is checked. This can be NULL, 
_ leaving the side of the menu bar blank when checked. A NULL value is not recommended,’ 


Example _ See the example under the GetMenuCheckMarkDimensions() function igi 

TrackPorurMENu = OWin2.0 mWin30 mWin31 

Purpose Displays a submenu anywhere on the screen. , 

Syntax BOOL TrackPopupMenu(HMENU hMenu, WORD wFlags, int x, int y, int nReserved, HWND 
hWnd, LPRECT [pReserved); 

Description This is a new option, added with the 3.0 version of Windows. The popup menu is displayed with its 


upper left corner at x,y on the screen. Screen coordinates are used, so the menu can be out of 
your program’s client area. Normal Windows menu item selection and WM_COMMAND messages: ... 
occur for the popup. The popup disappears ater a selection is made, or after another screen area 


is clicked. 
Uses Convenient if the normal drop- -down submenu options obscure an important part of the window’s 
| client area. — | 
Returns BOOL. TRUE if the function displayed the submenu, FALSE on error. 
See Also , CreatePopupMenu(), AppendMenu(), GetSubMenu() 
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Paranieters 


hMenu HMENU: A handle to the popup menu to be displayed. Use CreatePopupMenu() to make a new 
floating popup menu, and add the desired menu items with AppendMenu(). 

wFlags WORD: Not used. Always set to NULL. 

x int 

y int: The screen coordinates of the upper left corner. Use ClientToScreen() to convert from a 
desired location on the window's client area to screen cgordinates. : 

nReserved int: Not used. Always set to NULL. . 

hWnd HWND: A handle to the window that owns the popup menu. This is the window that will receive 
the WM_COMMAND messages from Windows as the submenu items are selected. 


lpReserved LPRECT: A pointer to a RECT data structure that contains the screen coordinates of a rectangle 
- - within which the user can click the mouse button without dismissing the popup menu. If set to 
NULL, the popup menu is dismissed if the mouse button is Ga mg teen 
i ge: nen. de lige 


clicked anywhere outside of the popup menu boundary. Prior 
to Windows 3.1, NULL was the only value permitted. 


Related Messages WM_COMMAND 


Example This example produces a window as shown in Figure 4-8. If the 
“Top Item” menu item is clicked, a floating popup appears at 
the lower left. Clicking the “Item one” menu item in the float- 
ing popup causes a simple message box to appear. 

The resource .RC file does not include the definition of 
the floating popup. Figure 4-8. Floating Popup 

Menu. 


Item one 


/* genmenu.rc _ wf 
#include <windows.h> 
H#Hinclude “genmenu.h" 


genmenu ICON generic.ico 

genmenu MENU 

BEGIN 
MENUITEM "&Top Item", IDM_TOP1 
‘MENUITEM "&Quit", IDM_QUIT 
MENUITEM “\a&Help", IDM_HELP, HELP 


END 


The floating popup menu is created when the program starts (WM_CREATE message re- 
ceived). It is displayed when the IDM_TOP1 menu item is clicked. Note that TrackPopupMenu() 
uses screen units for the X and Y position. The ClientToScreen() function converts the desired 
coordinates in the window’s client rectangle prior to calling TrackPopupMenu(). 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ; 


HMENU AhMenu ; 

static HMENU hPopupMenu ; 

POINT pFloater ; 

switch CiMessage) : /* process windows messages */ 
{ 


case WM_CREATE: 
hPopupMenu = Greatérasuenend ©); 
AppendMenu (hPopupMenu, MF STRING, IDM, POP, “Item &one.") ; 
AppendMenu ChPopupMenu, MF_STRING, IDM_POP2, “heen &two.") : 
break ; 

case WM_ COMMAND: /* process menu items */ 
switch (wParam) 7 
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[Other program lines] 


case IDM_TOP1: /* Top menu item disp. the float. popup */ 
-pFloater.x =0; /* put floating popup on Left side */ 
pFloater.y = 100 ; /* down 100 units */ 
ClientToScreen (hWnd, &pFloater) ; /* pt to screen */ 
TrackPopupMenu (hPopupMenu, NULL, pFloater.x, 

pFloater.y, NULL, hWnd, NULL) ; 2 

break ; 

case IDM_POP1: /* The first item in floating popup hit */ 


MessageBox (hWnd, "This floating menu works!", 
"Message", MB_OK) ; 
break ; . 


case IDM_QUIT: 
DestroyWindow (hWnd) ; - 
break ; 

} 

break ; 
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Mechanical equipment designed for people to manipulate settings (stereos, aircraft instruments, etc.) generally make 
use of buttons , knobs, and slide bars for changing values. These devices are much faster and more intuitive to use than 
typing at a keyboard. With aircraft instruments, keyboard entry is generally reserved for data that requires great 
precision, such as navigational settings. Buttons and slide bars (called “scroll bars” in Windows) are excellent ways to 
get user input. Rotating knobs do not have an exact match on the computer screen (rotating the mouse does not work 
well), so scroll bars are generally used in places where a machine might use a knob. In general, if your program 
requires the user to enter data on the keyboard, look for a way to provide a mouse alternative: Scroll bars for numeri- 
cal values, buttons for choices, and list boxes for selections from a list. This does not mean that keyboard input should 
be unsupported. Accelerator keys and other keyboard shortcuts find their way into most well-designed Windows pro- 
grams. The ideal program provides both keyboard and mouse alternatives for every action. 


Scroll Bar Concepts = 

Scroll bar controls are child windows. They are ‘initially created using the CreateWindow() function discussed in 
Chapter 2, Creating Windows, Once created, scroll bars can either be placed on the program’s client area, creating 
windows, or added as part of the window’s border, for scrolling the client area. Figure 5-1 illustrates three different 
scroll bars. 


Figure 5-1A (left), B (middle), C (right '). Three Examples of Scroll Bar Controls, 


Figure 5-1A shows a horizontal scroll bar that is attached to the window’s client area. It uses the SBS_HORZ style 
in CreateWindow(). Moving the scroll bar changes the numeric value in the edit control above it. The control could 
have been made into a vertical scroll bar by using the SBS_VERT style in CreateWindow(). This would also require 
changing the dimensions, to make the control thin in the X direction, and tall in the Y direction. Figures 5-1B and C 
show scroll bars that are attached to the window’s border and are not part of the client area. They are generally used 
as a way of scrolling the client area (moving the contents of the client area horizontally or vertically). If the scroll bar 
type shown in Figure 5-1A were used to scroll the client area, the scroll bar itself would be moved during scrolling! 
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The attachment of scroll bars to the window’s border is done when the scroll bar control is made visible. 
ShowScrollBar() is used for scroll bars the same way that ShowWindow() was used for other types of child windows. 
_ The difference is that ShowScrollBar() will attach scroll bars to the window’s border if the SB_HORZ or SB_VERT 
style is specified. Windows automatically subtracts the width cf the scroll bar from the client area, so that pairiting on 
the client area does not run over the scroll bars. The other way to get a scroll bar attached to a window’s frame is to 
create the window with one or two scroll bars specified when CreateWindow() is called. For example, to create a 
__ window with a horizontal scroll bar at the bottom (Figure 5-1B), add the WS_HSCROLL window style, as shown in the 
' - following code. 


hWnd = CreateWindow ( /* create the program's window here */ 

gszAppName, /* class name */ 
gszAppName, /* window name */ 
WS_OVERLAPPEDWINDOW | WS_HSCROLL, '  /* window style */ 
CW_USEDEFAULT, /* x position on screen */ 
CW_USEDEFAULT, /* y position on screen */ 

~ CW_USEDEFAULT, /* width of window */ 
CW_USEDEFAULT, /* height of window */ 
NULL, /* parent window handle (null = none) */ 
NULL, /* menu handle (null = use class menu) */ 
hInstance, /* instance handle */ .- 
NULL) ; /* tpstr (null = not used) */ 


ShowWindow (hWnd, nCmdShow) ; 


The WS_VSCROLL adds a vertical scroll bar, which can be done with WS_HSCROLL or separately. _ 

Defining the scroll bar as part of the parent window's CreateWindow() call is a handy shortcut, as it saves you . 
from having to create the window's scroll bars as separate child windows. The WndProc() function for the parent - 
window will receive WM_HSCROLL and/or WM_VSCROLL messages if the scroll bar i is moved with the mouse. The 
messages from the scroll bar will be sent using the parent window's handle. 

Scroll bars are attached automatically to list boxes when the number of items exceeds the size of the list window. 
List and combo boxes are discussed in Chapter 9, Windows Messages. Edit controls can also have scroll bars attached. 
Single line edit controls can only take advantage of the horizontal scroll bar, but multilirie edit controls can use both 
vertical and horizontal scroll bars. As edit controls are simply small windows, add the WS_HSCROLL and/or | 
WS_VSCROLL styles when creating the edit control. An example of a multiline edit control with a scroll bar is given 
in Chapter 9 under Edit Control Messages. 


Scroll Bar Position and Range 


When a scroll bar is first created, the range of values reflected by the two ends of the control are 0 to 100. This is only 
handy if you happen to be working with a parameter that varies over this range. In most cases, you will want to change 
_ the scroll bar range to match the data you are changing. For scrolling text, the range is probably equal to the number 
’ of lines of text. The SetScrollRan()_ gefunction allows the scroll bar range to be reset at any time. The value reflected 
by the scroll bar thumb (the rectangle in the center of the scroll bar that moves) depends on the scroll bar range. If 
the range is from one to ten, a value of five will set the thumb in the center. If the range is changed from one to twenty, 
a value of five will fall only one quarter of the way along the scroll bar. One thing you cannot do is reverse the top and 
bottom of a scroll bar. This is unfortunate, as the vertical scroll bars are set up with low values at the top and high 
values at the bottom. This is logical for scrolling text, but is reversed relative to what you would expect for entering a 
number. You can get around this by subtracting the scroll bar position from the maximum position to get the value the 
user meant when entering a number. 


Scroll Bar Messages 


When the user clicks part of a scroll bar, Windows sends either a WM_HSCROLL or WM_VSCROLL message, corre- 
sponding to the action on a horizontal or vertical scroll bar, respectively. The wParam parameter that gets passed to 
your WinProc() function with the message will tell where on the scroll bar the mouse was located when the user, 
clicked the mouse button. These wParam values have names in WINDOWS.H (like SB_LINEUP for the top or left side 
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arrow). Figure 5-2 shows the wParam values for each 
part of the scroll bar. Ifyou look in WINDOWS.H, you will 
find two additional scroll bar messages, SB_TOP and 
SB_BOTTOM. The author has been unable to get a scroll 
bar to send one of these messages. When the mouse but- 
ton is released after an action on the scroll bar, Windows 
sends an SB_ENDSCROLL message. The exception to 
this is if the user was moving the scroll bar thumb. In 
this case, releasing the mouse generates the Bei 
SB_THUMBPOSITION message. The complete descrip- Figure 5-2. Scroll Bar eaesane 
tion of each of these messages is given in Chapter 9, Win- 

dows Messages. 


SB_LINEUP 


SB_PAGEUP 


SB_THUMBTACK (Pressed) 
S8B_THUMBPOSITION (Released) 


SB_PAGEDOWN 


SB_LINEDOWN 


Scroll Bar Function Summary 


The functions relating directly to scroll bars are summarized in Table 5-1. Most of them deal with the simple tasks of 
setting and retrieving the scroll bar range and thumb position. | 


Function Purpose ae . | 
EnableScroliBar Enable or disable a scroll bar control (Win 3.1). 
- GetScroliPos Retrieve the current position of the scroll bar’s thumb. 
GetScroliRange Retrieve the minimum arid maximum value range of a scroll bar. “s 
ScrollDC Scroll a region in a device context and compute the update areas. 
ScrollWindow Scroll a region in a window's client area. 
SetScrollPos Set the position of the scroll bar thumb. 


SetScrollRange Set the minimum and maximum values of a scroll bar. 
ShowScrollBar Display the scroll bar, optionally attaching it to the window’s border. 


Table 5-1. Scroll Bar Function Summary. 


The two functions that are more complex are ScrollWindow() and ScrollDC(). They both scroll an area horizon- 

~ tally and/or vertically. ScroliIDCQ) is more sophisticated, as it computes the areas on the screen that need to be 

updated after scrolling. Scrolling always uncovers areas on the screen that need to be repainted. Your program logic 
can determine what action to také depending on the size and location of the areas that need to be updated. 


ENABLESCROLLBAR . OWin2.0 OWin3.0 wWin31 
' ‘Purpose Enables or disables a scroll bar control. 
| Syntax BOOL EnableScrollBar (HWND hWnd, WORD wSBFlags, WORD wArrowFlags); 

Description When a scroll bar is disabled, the thumb disappears and the center portion is not shaded. No 


action or messages occur if the user attempts to use the scroll pat. When activated, the thump 
reappears, and the center portion is shaded. 


Uses - The scroll bar can be disabled when the contro} it is attached to loses the input focus. pee the 
example below for an edit control. 
Returns BOOL. TRUE if the function was successful, FALSE on error. 


See Also SetFocus() 
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Parameters - 


hWnd _ HWND: The scroll bar window handle. This can be either a stand-alone scroll bar or a scroll bar 
attached to another window, depending on the wSBFlags value. If the scroll bar is created as part 
of the window's style (WS_VSCROLL or r WS | HSCROLL), the created window’s handle is used for . 
. hWnd. 
wSBFlags _ WORD: The ee of scroll bar. This can be any of the types described in Table 5-2. 
jue Meaning © eee eS 
SB_BOTH Both horizontal and vertical scroll bars attached to a window. 
SB_CTL A scroll bar control. In this case, set hWnd equal to the scroll bar handle. 
SB_HORZ A horizontal scroll bar tied to the window. In this case, hWnd should be the window's handle, 
SB_VERT . A vertical scroll bar tied to the window. In this case, hWnd should be the window's handle. 


Table 5-2. Scroll Bar Types. 


wArrowFlags WORD: Specifies whether the scroll bar is enabled or disabled. It can be ay of the following 
values described in Table 5-3. 


~ Meaning. . 


ESB_ENABLE_ BOTH Enables both arrows oft the sarak ey 
ESB_DISABLE_LTUP Disables the left arrow of a horizontal scroll bar, or the down arrow of a vertical scroll bar. 
ESB_DISABLE_RTDN Disables the right arrow of a horizontal scroll bar, or the up arrow of a vertical scroll bar. 


ESB_DISABLE_BOTH Disables both arrows of a scroll bar. 
Table 5-3. Scroll Bar Types. 


Example This example creates an edit control with an attached horizon- 
tal scroll bar. The scroll bar is only activated when the edit 
control has the input focus. If the focus shifts to another win- | 
dow, the scroll bar is deactivated.. Windows sends a 
WM_COMMAND message with the edit control's ID value as 
wParam when the scroll bar is activated. The scroll bar notifi- 
cation code is decoded by examining the high-order word of 
the /Param value passed with WM_COMMAND. EN_SETFOCUS = Figure 5-3. EnableScroll- 
is the notification code sent when an edit control gains the Bar() Example. 
input focus. EN_KILLFOCUS is the notification code when the ca 
edit control loses the input focus. Figure 5-3 illustrates the use of EnableScrollBar(). 


Do It! Quit 


Contents = Text In Edit Control 


* tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
C 


static HWND hEdit ; 


HDC hDC ; 

char cEditBuf (641, cBuf [£128] ; 

switch CiMessage) /* process windows messages */ 
{ 


case WM_ CREATE: 
hEdit = CreateWindow C"EDIT", “Y, : 
- WS_CHILD | WS_BORDER [| WS_| HSCROLL I ES_AUTOHSCROLL I! 
ES SNUREEC INE: 
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10, 10, 100, 50, hWnd, 101, ghInstance, NULL) ; 
SetWindowText ChEdit, "Text In Edit Control") ; 
ShowWindow ChEdit, SW_SHOW) ; ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case 101: /* edit control notification */ 
switch CHIWORD CLParam)) 
{ 
, case EN_SETFOCUS: 
EnableScrotlBar ChEdit, SB_HORZ, 
ESB_ENABLE_BOTH) ; 
break ; 
case EN_KILLFOCUS: 
EnableScrottBar ChEdit, SB_HORZ, 
ESB_DISABLE_BOTH) ; 
break ; 
} 
break ; 
case IDM_DOIT: /* retrieve edit text and display */ 
GetWindowText ChEdit, cEditBuf, 63) ; 
hdC = GetDC ChWnd) ; 
TextOut (hDC, 10, 70, cBuf, wsprintf (cBuf, 
“Contents = %s", (LPSTR) cEditBuf)) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
PostQuitMessage (NULL) ; 
‘break ; 
} 
break ; 
case WM_DESTROY: 
PostQuitMessage cODs 
break ; 
default: 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 


} 
return COL) ; 


} 
GeETScROLLPos BWin2.0 mWin30 mWin31 
Purpose Finds the location of the scroll bar thumb. 
Syntax int GetScrollPos(HWND hWnd, int nBar); 
Description Reads the position of the scroll bar thumb. The number returned will depend on the scroll bar 
range that was set with SetScrollRange(). 
Returns int, the scroll bar position. ; 
See Also SetScrollPos(), SetScrollRange, GetScrollRange() : 
Parameters 
hWnd HWND: The scroll bar control handle if nBar is SB_CTL, or the window handle if nBar is 
: SB_HORZ or SB_VERT. 
nBar int: The type of scroll bar. This can be any of the types listed in Table 5-4. 
SB_CTL A scroll bar control. in this case, set hWnd equal to the scroll bar handle. 
SB_HORZ ‘A horizontal scroll bar tied to the window. In this case, hWnd should be the window’s handle. 
SB_VERT A vertical scroll bar tied to the window. In this case, hWnd should be the window's handle. 


Table 5-4. Scroll Bar Types. 
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Related Messages WM_HSCROLL, WM_VSCROLL = | —* - “generic ° FTE 


Scroll Position = 4 


Example Here the program creates a scroll bar control that sets the nu- 
meric value inside the edit control when the scroll bar is 
moved. When the user clicks the “Do It!” menu item, the cur- 
rent scroll bar position is retrieved by GetScrollPos() and dis- 
played in the client area, as illustrated in Figure 5-4. 


Figure 5-4. GetScrollPos() 
Example. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


static HWND Edit, hScroll ; 
static int nScroltlValue ; 
‘char cBuf (128) ; 
HDC . hDdC ; 
int . nN; 
switch (iMessage) , /* process windows messages */ 
case WM_CREATE: /* create edit control */ 


_ hEdit = CreateWindow ("EDIT", "O", 

WS_CHILD | WS_VISIBLE | WS_BORDER, 

20, 20, 40, 25, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow ChEdit, SW_SHOW) ; . 

/* create scrolt bar control */ 
hScroll = CreateWindow ("SCROLLBAR", "", 

WS_CHILD | WS_VISIBLE | SBS_HORZ, 

10, 100, 200, 20, hWnd, NULL , ghInstance, NULL) ; 
ShowScrollBar ChScroll, SB_CTL, SW_SHOW) ; 
SetScrotlRange (hScroll, SB_CTL, 0, 10, FALSE) ; 
nScrollValue = 0 ; 

SetScrollPos (hScroll, SB_CTL, nScrollValue, TRUE) ; 
break ; 

case WM_HSCROLL: 
switch (wParam) 


case SB_THUMBPOSITION: _. /* user has moved scroll thumb */ 
nScrollVatue = LOWORD (LParam) ; 
SetScrollPos ChScroll; SB_CTL, nScroltVatue, TRUE) ; 
wsprintf (cBuf, "“Zd",. ‘nScroltVatue) : 
SetWindowText ChEdit, (LPSTR) cBuf) ; 
break ; oot ad 
case SB_ LINEDOWN: /* user clicked scroll rt arrow */ 
nScrollValue++ 3 
nScrollValue = nScrollValue > “40 2-10 : nScrotlValue ;_ . 
SetScrollPos (hScrolt, SB_CTL, nScrollValue, TRUE) ; 
wsprintf (cBuf, "Z%d", ‘nScroltVatue) i: 
SetWindowText ChEdit, (LPSTR) cBuf) ; 
break ; Ra eee sre 
case SB_LINEUP: - /* user clicked scrotl Lf arrow */ 
nScrollValue-— ; ‘ ; 
nScrollValue = nScrollValue <0? 0: nScrollValue ; 
SetScrollPos (hScroll, SB_CTL, nScrollValue, TRUE) ; 
wsprintf (cBuf, "%d", nScrollValue) ; 
SetWindowText (hEdit, (LPSTR) cBuf) ; 
break ; 
} . . 
break ; . 
case WM_COMMAND: ; : /* process menu items */ 
switch (wParam) 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
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n= GetScrollPos (hScroll, SB_CTL) ; 
hDC = GetDC ChWnd) ; 
TextOut (hDC, 25, 0, cBuf, wsprintf (cBuf, 
"Scroll Position = %d", n)) ; 
Rereesene ChWnd, hOC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; 
case WM_DESTROY: /* Stop application */ 
pos cu LeNsceage (0) ; 
break ; 
default: /* default windows message processing si 
return DefWindowProc (hWnd, umes aage7 wParam, lParam) ; 
} 
return (OL) ; 
} 
GETSCROLLRANGE | mWin2.0 3 mWin30 3 mWin3l 
Purpose Retrieves the minimum and maximum range values for a scroll bar. 
Syntax . void GetScrollRange(HWND hWnd, int nBar, LPINT lpMinPos, LPINT lpMaxPos); 
Description Sets the integer values pointed to by IpMinPos and lpMaxPos to the scroll bar limits. 
Uses Avoids having to keep track of scroll bar limits in static variables. You can retrieve the scroll bar 
limits when you use GetScrollPos() to retrieve the scroll bar position. 
Returns No returned value (void). 
See Also GetScrollPos(), SetScrollRange, SetScrollPos() 
Parameters . 
hWnd . HWND: The scroll bar control handle if nBar is SB_CTL, or the window handle if nBar is 
SB_HORZ or SB_VERT. . 
nBar - int: The type of scroll bar. This can be any of the types listed in Table 5-5. 
Meaning © PgR aE a ah 
$B_CTL Ascroll bar control. In this case, set hWnd ae to the scroll bar handle. 
SB_HORZ A horizontal scroll bar tied to the window. In this case, hWnd should be the window's handle. 
SB. VERT ~~ Avertical scroll bar tied to the window. In this case, hWnd should be the window's handle. 


Table 5-5. Scroll Bar Types. 


_ - generic * [- [= 


lpMinPos LPINT: A pointer to the integer variable that will receive the 
‘ "minimum scroll bar value range. 
lpMaxPos LPINT: A pointer to the integer variable that will receive the 


maximum scroll bar value range. 
Related Messages WM_HSCROLL, WM_VSCROLL 


Example. This example (illustrated in Figure 5-5) demonstrates’a win- 
dow with an attached horizontal scroll bar. The scroll bar is 
created with the window during the CreateWindow() call in 
WinMain(). The scroll bar range and initial position are set when the WndProc() function pro- 
cesses the WM_CREATE message. When the user clicks the “Do It!” menu item, the scroll bar 
ranges are displayed in the client area. , 


Scroll Min Range. = 0 
Scroll Max Range = 10 
iB 


Figure 5-5. GetScrollRange( ) 
Example. 
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/* generic.c generic windows application a] 


#include <windows.h> /* window's header file - always included */ 
Hinclude “generic.h" /* the application's header file */ 


int PASCAL WinMain (HANDLE hInstance, HANDLE hPrevinstance, LPSTR LpszCmdLine, 
int nCmdShow) 


{ 
“HWND hWnd ; 
MSG msg ; 
‘WNDCLASS wndclass ; 
ghInstance = hInstance ; /* store instance handle as global var. */ 
if (!hPreviInstance) /* load data into window class struct. */ 
{ 
wndclass.style = CS_HREDRAW | CS_VREDRAW ; 
wndclass.lpfnWndProc = WndProc ; 
wndclass.cbClsExtra =0; 
wndclass.cbWndExtra =0; 
wndclass.hInstance = hInstance ; 
wndclass.hIcon = LoadiIcon (hInstance, gszAppName) ; 
_wndclass.hCursor = LoadCursor (NULL, IDC_ARROW) ; 
wndclass.hbrBackground = GetStockObject (WHITE ~BRUSH) ; 
wndclass.lpszMenuName = gszAppName ; 
wndclass.lpszClassName = gszAppName ; 
/* register the window class */ 
if (!RegisterClass (aundelass)) 
return FALSE ; 
} 
hWnd = CreateWindow ( /* create the program's window here */ 
gszAppName, /* class name */ 
gszAppName, /* window name */ 
WS_OVERLAPPEDWINDOW | WS_HSCROLL, /* window style */ 
CW_USEDEFAULT, /* x position on screen */ 
CW_USEDEFAULT, ‘/* y position on screen */ 
CW_USEDEFAULT, /* width of window */ 
CW_USEDEFAULT, /* height of window */ 
NULL, : /* parent window handle (null. = none) */ 
NULL, © - /* menu handle (null = use class menu) */ 
hInstance, ., /* jnstance handle */ : 
NULL) ; 5 /* Lpstr (null = not used) */ 
ShowWindow ChWnd, nCmdShow) ; 
UpdateWindow (hWnd) ; /* send first WM PAINT message */ 
while (GetMessage (&msg, NULL, 0, 0)) . /* the message Loop */. 
{ ; 
TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} 
return msg.wParam ; 
} ss 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 
char cBuf [128] ; 
HDC hoc ; 
int nMin, nMax ; 
switch (iMessage) /* process windows messages */ 
{ 


case WM_| CREATE: 
SetScrollRange (hwnd, SB_HORZ, 0, 10, FALSE) : 
perc roctles ChWnd, SB_! MOR? 5, TRUE) ; 
break ; ‘ 
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} 


ease WM_COMMAND: 


/* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
GetScrollRange chind , SB_. HORZ, &nMin, &nMax) ; 
hDC = GetDC ChWnd) ; 
TextOut (hDdC, 0, 0, cBuf, wsprintf (cBuf, 
“Scroll Min Range. = %d", nMin)) ¢; 
TextOut (hDC, 0, 20, cBuf, wsprintf (cBuf, 
"Scroll Max Range = %d", nMax)) ; 
ReleaseDC ChWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow ChWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 


return (OL) ; 


Scro_ttDC 


Purpose 
Syntax 


Description 


Uses 
Returns 
See Also 
Parameters 
hDC 

dx 

dy 
lprcScroll 


lpreClip 


hrgnUpdate 


w@Win2.0 m8Wind0 mWin3l 


Scrolls all or part of a device context vertically and/or horizontally. 

BOOL ScrollDC(HDC hDC, int dx, int dy, LPRECT lprcScroll, LPRECT lprcClip, HRGN 
hrgnUpdate, LPRECT lprcUpdate), 

This function is the most powerful method of moving a rectangular region of bits. The movement 
can be both horizontal and vertical in one function call. A subregion within the scrolling rect- 
angle can be picked out, limiting the area scrolled. The function also computes the size of either 
an update region or update rectangle, capturing the area that needs to ad repainted after scroll- 
ing to keep the image intact. 

Scrolling a window’s client area, or scrolling all o or part of a bitmap i in a memory device context. 
BOOL. TRUE if the function executed correctly, FALSE on error. 
ScrollWindow() 


HDC: The device context that contains the image to be scrolled. Use GetDC() to obtain a 
window’s device context. 

int: The number of units to scroll horizontally. Positive numbers scroll right, tlegative numbers 
scroll left. 

int: The number of units to scroll vertically. Positive numbers scroll down, negative numbers 
scroll up. 

LPRECT: Pointer to the rectangle structure that contains the coordinates of the scrolling rect- 
angle. Use GetClientRect() to obtain a window's client area rectangle. . 

LPRECT: Pointer to the rectangle structure that contains the coordinates of the clipping rect- 
angle. If the lpreClip rectangle is smaller than TESS only the area inside the [prcClip rect- 
angle is scrolled. 

HRGN: A handle to the update region uncovered by the scrolling process. If scrolling is in both 
the X and Y directions simultaneously, the region will not be rectangular. If hrgnUpdate and 
IprcUpdate are both NULL, Windows does not compute the update region. 
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lgrcUpdate LPRECT: A pointer to a rectangle structure that is filled with [gen 


generic 


the dimensions of the smallest rectangle that bounds the up- 
date region uncovered by the scrolling process. Set to NULL if 
you do not want Windows to compute the update rectangle. 


Related Messages WM_HSCROLL, WM_VSCROLL 


Example - This example uses ScrollDC to scroll the center part of the 
window's client region, based on the window’s horizontal scroll 
bar position. The clipping region is set smaller than the client _ 
area by 20 units, so that the outermost 20 units are not scrolled. Figure 5-6. ScrollDC() 
After the user clicks the “Do It!” menu item (drawing the lines) Example. 
and gives one mouse click of the right scroll bar arrow, the 


window looks like Figure 5-6. 

Long FAR PASCAL WndProc CHWND. hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
C Js : 

static HWND hScroll ; 

static int nScrollValue, nOldValue ; 

HDC hoc ; 

int i; 

RECT : rWind, rClip, rUpdate ; 

HRGN hrgnUpdate ; ‘ 

HANDLE hPen ; 

switch (iMessage) /* process windows messages */ 

{ ' 


case WM_CREATE: 
GetClientRect (hWnd, &rWind) ; 
hScroll = CreateWindow ("SCROLLBAR", "'", 
WS_CHILD {| WS_VISIBLE | SBS_HORZ | SBS_BOTTOMALIGN, | 
rWind. left, rWind.top, rWind.right, rWind.bottom, 
hWnd, NULL , ghInstance, NULL) ; 
ShowScrollBar (hWnd, SB_HORZ, TRUE) ; | - 
SetScrollRange (hWnd, SB_HORZ, 0, 10, FALSE) ; — 
-nScrollValue = nOldValue = 0 ; 7 
SetScrollPos (hWnd, SB_HORZ, nScrollValue, TRUE) ; 
break ; 
case WM_HSCROLL: ; : 
hrgnUpdate = CreateRectRgn (0, 1, 2, 3) ; 
hDC = GetDC ChWnd) ; 
GetClientRect (hWnd, &rWind) ; /* get client rectangle */ 
rClip.left = rWind. left + 20 ; /* set clipping region */ 
rClip.right = rWind.right - 20 ; /* inside of client rect */ 
rClip.top = rWind.top + 20 ; : 
rClip.bottom = rWind.bottom — 20 ; 
switch (wParam) 
£ ” 
case SB_THUMBPOSITION: /* user has moved scroll thumb */ 
nScrollValue = LOWORD (lParam) ; 
if (nScrollValue != nOldValue) 
4 
SetScrollPos (hWnd, SB_LHORZ, nScrollValue, TRUE) ; 
ScrollDC ChDC, - 
20 * (nScrollValue - nOldValue), 0, 
CLPRECT) &rWind, (LPRECT) &rClip, 
-hrgnUpdate, CLPRECT). &rUpdate) ; 
n0OldValue = nScrollValue ; 
} : : 
break ; 
case SB_LINEDOWN: /* user clicked scroll rt arrow * 
, nScrollValue++ ; a? 
-nScrollValue = nScrollValue > 10 ? 10 : nScrollValue ; 
if (nScrollValue != nOldValue) 
Ct 
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SetScrollPos (hWnd, SB_HORZ, nscrottvalue, TRUE) ; 
ScroltbdCc ChDC, 
20 * (nScrollValue - nOldValue), 0, 
CLPRECT) &rWind, (LPRECT) arClip, 
hrgnUpdate, CLPRECT) &rUpdate) ; 
nOldValue = nScrollValue ; 
} 
break ; 
case SB_LINEUP: /* user clicked scroll Lf arrow */ 
nScrollValuen ; : 
nScrollVatue = nScrollValue <0 20: nScrollValue ; 
if (nScrollValue != nOldValue) 


{ 
SetScrollPos ChWnd, SB_HORZ, nScrollValue, TRUE) ; 
ScrollLDOC ChDdC, 
20 * (nScrollValue —- nOtdValue), 0, 
CLPRECT) &rWind, CLPRECT) &rClip, 
hrgnUpdate, CLPRECT) &rUpdate) ; 
nOldValue = nScrollValue ; 
} 
break ; 


} 
ReleaseDC ChWnd, hDC) ; 
DeleteObject (hrgnUpdate) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ , 
case IDM_DOIT: /* User hit the "Do it” menu item */ 


hDC = GetDC (hWnd) ; 
hPen = GetStockObject (BLACK_PEN) ; 
for (i =0; i< 20; i++) /* paint 20 lines */ 


MoveTo (hOC, i * 8, 0) ; 
LineTo (hDC, i * 8, 400) ; 

} 

DeleteObject (hPen) ; 

ReteaseDC (hWnd, hDC) ; 

break ; 

case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} > 
return (OL) ; 
} 
ScrRoLLWINDOw mWin2.0 mWin3d0  mWin3.1 
Purpose Scrolls a window’s client area in the X and Y directions. 
Syntax void ee hWnd, int XAmount, int VAviount, LPRECT lpRect, LPRECT 
lpClipRect); 
Description > This is a simpler scrolling function than ScrollDC(), but it lacks the ability to compute regions or 
i rectangles uncovered by the scrolling process. Instead the uncovered areas are automatically 
placed into the window's update region for painting on the next WM_PAINT cycle. 
Uses . Scrolling small windows where separate logic is applied to compute the uncovered regions. 


Returns No returned value (void). 
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See Also 
Parameters 


hWnd 


SAmount 


YAmount 


IpRect 


lpClipRect 


\ 


Related Messages 


Example 


ScrollDC() 


HWND: The hanate of the window that has the client a area that 
will be scrolled. 


int: The amount to scroll the window in the. XY diveeifon Device 
units are used. Positive values scroll right, negative values 
scroll left. , ; 


= oft.) generic. - ire 
number line is here. 
number line is here. 
neary line if here. 


number line is here. 
number line is here. 


number line ie here. 


int: The amount to scroll the window in the ¥ direction. Device Figure a- ” Scroll 1Window( 7 


units are used. Positive values scroll down, negative values Example. 


scroll up. 


LPRECT: A pointer to a rectangle structure containing the portion of the client area to be 
scrolled. NULL ifthe entire client area‘is to be scrolled. Use GetClientRect() to determine the 


bounding rectangle of the client area if-you will be scrolling a portion of it. 


LPRECT: A pointer to a rectangle structure that contains the clipping rectangle to be scrolled. If 
the clipping rectangle is within tne (pRect area, only points within /pClipRect will be scrolled. Set 


equal to NULL if the entire window. is to be scrolled. 
WM_HSCROLL, WM VSCROLL 


This example, illustrated in Figure 5-7, scrolls some text in the client area, based on the nisition 
of the horizontai scroll bar at the window’s bottom. The text is initially painted when the user 
clicks the “Do It!” menu item. Because there is no automatic repainting of clipped text on the 
right side, scrolling the text into the window's side causes the end of the text to be lost. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ; 


static 
static 
char 
HDC 
int 
RECT 


switch CiMessage) 


t 


HWND “hScroll ; 

int nseroltValue, noldvalue i 
cBuf (10) ; 

BDe 


case WM_CREATE: 
GetClientRect hwnd, &rWind) ; 
hScroll = CreateWindow C"SCROLLBAR", "", 


/* process windows messages */ 


-WS_CHILD | WS_VISIBLE | SBS_HORZ | SBS_BOTTOMALIGN, 
rWind.left, rWind.top, rWind.right, rWind.bottom, 


hWnd, NULL , ghInstance, NULL) ; 

ShowScrollBar ChWnd, SB_HORZ, TRUE) ; 
SetScrollRange (hWnd, SB_HORZ, 0,10, FALSE) ; 
nScrollValue = nOldValue = 0 ; 
SetScrollPos (hWnd, SB_HORZ, nScrollValue, TRUE) ; 
break ; 

case WM_HSCROLL: 
switch (wParam) 
cf 


nScrollValue = LOWORD (LParam) ; 
if (nScrollValue != n0ldValue) 
{ 


\ 


case SB_THUMBPOSITION: /* user has moved scroll thumb */ 


SetScrollPos (hWnd, SB_HORZ, nScrollVaLlue, TRUE) ; 


ScrollWindow ChWnd, 


20 * (nScroltValue - nOldValue), 


o, NULL, NULL) ; 
AbLdvatue = nScroltValue : 
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} 
break ; 

case SB_LINEDOWN: /* user clicked scroll rt arrow */ \ 
nScrollValuet+ ; i : : 
nScrollValue = nScrollVatue > 10 210: 2 nScrollValue : 
if (nScrollValue != nOldValue) \ 


t 
SetScrollPos (hWnd, SB_HORZ, nScrollValue, TRUE) ; 
ScrollWindow ChWnd, 
20 * (nScrollValue — noldValue), 0, 
NULL, NULL) ;, ; 
nOldValue = nScroltVatue 5 
} 
break ; : 
case SB_LINEUP: /* user clicked scroll lf arrow */ 


nScrollValuen ; 
nScro(lValue = nScrotlValue <0? 0 : nScrollValue ; 
if (nScrollValue != nOldValue) 


{ 
_ SetScrollPos (hWnd, SB_HORZ, nScrollValue, TRUE) ; 
ScrollWindow ChWnd, 
20 * (nScrolLValue - nOldValue), 0, 
NULL, NULL) ; : 
nOldValue = vechottvalie ; 
} 
break ; 
} 
break ; . 
— case WM_COMMAND: /* process menu items */ 
switch (wParam) ; 
{ 
case IDM_DOIT: /* User hit the “Do it" menu item */ 
hDC = GetDC ChWnd) ; 


for (i =0; i < 20 ; i++) /* draw some text */ 


itoa (i, cBuf, 10) ; 

TextOut (hdc, 0, i * 20, cBuf, strlen (cBuf)) ; 

TextOut ChDC, 20, i * 20, 

“number. Line is here.", 20) ; 

} $ 
ReleaseDC (hWnd, hoc) ; 
break ; 

case IDM_QUIT: 

' DestroyWindow ChWnd) ; 


break ; 
} 
break ; 
case WM_DESTROY:” /* gods application *] 
Postaui thessage (0) ; 
break ; 
' default: /* default windows message processing hes 
return DefWindowProc (hWnd, iMessage, wParam, |Param) ; 
} 
return COL) ; 
+ - 
SETSCROLLPOs | wWin20 m8 Win30 ‘mWin31 
Purpose Sets the position of the scroll bar thumb. 
Syntax int SetScrollPos(HWND hWnd, int nBar, int Pos, BOOL bRedraw); 
Description The physical location after the thumb depends on the ranges set for the scroll bar’s minimum and 


maximum values. The thumb’s position will be ratioed between these two extremes. Values be- 
yond the limits of the scroll bar range result in the thumb at an end of the scroll bar (no danger of 


going past limits). 
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Uses Generally used when the scroll bar is first created or shown, to make the thumb position match 
: the value represented. It can also be used for building keyboard interface functionality. 
Returns int, the previous position of the scroll bar thumb. 
See Also SetScrollRange(), GetScroliPos(), Gomerallmanee() 
Parameters | 
hWnd HWND: The scroll bar control handle if nBar is SB _CTL, or the window handle if nBar is 
. SB_HORZ or SB_VERT. 
nBar int: The type of scroll bar. This can be any of the types listed in Table 5-6. 


SB _CTL A Sue ba cone In this case, set hWnd equal to the scroll bar handle. 
SB_HORZ Ahorizontal scroll bar tied to the window. In this case, hWnd should be the window's handle, 
SB_VERT A vertical scroll bar tied to the window. In this case, hWnd should be the window's handle. 


Table 5-6. Scroll Bar Types. 


nPos int: The new scroll bar thumb position. 


bRedraw BOOL: TRUE if the scroll bar should be redrawn to show the new thumb position, PALSE if not. 
Use it if you are going to call another scroll bar function, which will then redraw. 


Related Messages WM_HSCROLL, WM_VSCROLL 


Example See the following example under the SetScrollRange() function description. 

SETSCROLLRANGE a mWin2.0 mWin30 mWin3.1 

Purpose Establishes the upper and lower ranges of a scroll bar. 

Syntax _ void SetScrollRange(HWND hWnd, int nBar, int nMinPos, int nMaxPos, BOOL bRedraw); 

Uses . . Used when the scroll bar is created to establish the upper and lower limits of the scroll bar range. 

Returns No returned value (void). 

See Also SetScrollPos(), GetScrollRange(), GetScrollPos() 

Parameters 

hWnd HWND: The scroll bar control handle if ane is SB_CTL, or the window handle if nBar is 
SB_HORZ or SB_VERT. 

nBar | int: The type of scroll bar. This can be any of the sips listed i in Table b- 7. 


SB_CTL A scroll bar control. In this case, set hWnd equal to the scroll bar handle. - 
SB_HORZ A horizontal scroll bar tied to the window. In this case, hWnd should be the window's handle. 
SB_VERT. A vertical scroll bar tied to the window. In this case, hWnd should be the window's handle. 


Table 5-7, Scroll Bar nee 


160. 


nMinPos 
nMaxPos 
bRedraw 
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int: The scroll bar lower limit. 

int: The scroll bar upper limit. - b 

BOOL: TRUE if the scroll bar should be redrawn to show the new thumb position, FALSE if not. 
Use it if you are going to call another scroll bar function, which will then redraw. 
WM_HSCROLL, WM_VSCROLL ; 


This example creates a scroll bar control and attaches it to the main window. The scroll bar range 
is set from 0 to 10, and the thumb moved to a value of zero. Note how ShowScrollBar() is used to 
attach the scroll bar (a child window) to the application’s main window. _ 


oa 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


4a 


static HWND hScroll ; 
RECT rWind ; 
, switch CiMessage) /* process windows messages */ 


case WM_CREATE: 

GetClientRect (hWnd, &rWind) ; 

hScroll = CreateWindow ("SCROLLBAR", “", 
WS_CHILD {| WS_VISIBLE | SBS_HORZ | SBS_BOTTOMALIGN, 
rWind. left, rWind.top, rWind.right, rWind. bottom, 
hWnd, NULL , ghInstance, NULL) ; 

ShowScrollBar ChWnd, SB8_HORZ, TRUE) ; 

SetScrollRange (hWnd, SB_HORZ, 0, 10, FALSE) ; 

nScrollValue = nOldValue = 0 ; 

SetScrollPos ChWnd, SB_HORZ, nScrollValue, TRUE) ; 


break ; 

[Other program lines] 

SHOWSCROLLBAR mWin2.0 mWin3.0 mWin31- 

Purpose Makes a scroll bar visible and establishes its links to the parent window (if any). 

Syntax void ShowScroliBar(HWND hWnd, WORD wBar, BOOL bShow); 

Description Shows or hides a scroll bar. This function should be used rather than ShowWindow() to make 
scroll bars visible. ShowScrollBar() allows a horizontal or vertical scroll bar to be linked to a 
window’sframe..  / 

Uses Used during the initial creation of a scroll bar, or later to hide or redisplay the scroll bar. Do not 
call this function while processing a scroll bar message. 

Returns No returned value (void). 

See Also ShowWindow() 

Parameters 

hWnd HWND: The scroli bar control handle if »Bar is SB_CTL, or the window handle if nBar is 
SB_HORZ or SB_VERT. | 

nBar int: The type of scroll bar. This can be any of the types listed in Table 5-8. 
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Meaning 


SB_BOTH Both horizontal and vertical scroll as series to a window. 

SB_CTL a A scroll bar control. In this case, set hWnd equal to the scroll bar hende 

SB_HORZ a: horizontal scroll bar tied to the window. In this case, hWnd should be the window’ s handie. 
SB_VERT ~ A vertical scroll bar tied to the window. In this case, hWnd should be the window’s handle. 


Table 5- 8 ‘Scroll Bar Types. e 7 Lo 


Siew: ‘BOOL: TRUE if the scroll bar is to be visible, FALSE if it is to be hidden. 


Example See the previous example under the SetScrollRange() function description. 
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The mouse is used extensively in Windows programs for many purposes. Windows provides excellent built-in support 
for controlling the mouse. Windows also supports a related concept, the “caret.” This is a blinking line (or shape) that 
can be positioned in the client area to highlight a position. Typically, it is used in word processing applications to show 
where the next keyboard input will be as text is entered on the screen. Using the caret to fix locations on the screen 
allows the mouse cursor to be free for menu selections and other uses that take it off the window's client area. 
Physically, the mouse cursor is a small bitmap that is displayed and erased at different locations on the screen to 
produce the illusion of movement. This bitmap shape can be changed as the program runs. Many applications can be 
improved by having the mouse cursor shape change from the usual arrow shape to something more appropriate for the 
activity. “Pen” shapes for drawing, “hands” for pushing buttons, and even “little men” for playing games are possible. 
The Windows versions 3.0 and higher support dynamically changing the shape of the cursor as the program runs and 
basing the cursor shape on bitmap images. 


Mouse Message Overview 
From the programmer’ s point of view, the mouse interacts with a program by sending a series of messages. A good way 
~ to get a feel-for this message flow is to turn on the Windows Spy program that comes with the Software Development 
Kit (SDK). Set Spy to receive messages from all windows. A typical Spy screen is shown in Figure 6- 1 
‘In this example, Spy is tracking messages sent to a : 
program called SNAP. Here are the first three messages’ SS sree: > Spy = SNARBSnap3 es. Soa, 


and how to interpret them. ‘Spy Window Options! 
WM_SETCURSOR 200C WM_SETCURSOR 02000005 he 
9200C WH _NCMOUSEMOVE 01700137 
Windows tses this message if it ae to change the 200C WM_NCHITTEST 01700137 
cursor shape. 200C WhM_MOUSEACTIVATE 02010005 
200C WM_NCPAINT oogo0c00 
WM_NCMOUSEMOVE 200C WM_NCACTIVATE 00002094 
The mouse cursor has moved within a nonclient area 200C WM_SETCURSOR 02010005 
of the window. . 200C WM_NCLBUTTONDOWN 01700137 
200C WM_SETCURSOR pease 
WM_NCHITTEST - 200C WM_NCCALCSIZE 


This message tests what type of object the cursor is §200C WM_NCPAINT socoo000 
over (for example, border, caption, client area, etc.). 2006 WM_NCACTIVATE : 00202094 Fy 
The values shown in hexadecimal on the right side Figure 6-1. Windows Spy Program Viewing Mouse 

of the Spy window are the wParam and lParam data Messages. 

that is sent with the message. wParam is a WORD, so it 

_ only has 16 bits of information, but Param contains 32 bits. These parameters are used to encode the mouse position 
on the screen, and encode the data about wnat type of object the mouse cursor is above. We will examine these fields 
in a moment. 

After a little fooling around with Spy, you will realize that Windows sends a lot of messages to your program as you 
move the mouse or use its buttons. Fortunately, most programs can ignore the majority of these messages and just 
pass them to the default window's procedure. The messages that you are most likely to use are WM_MOUSEMOVE, 
WM_LBUTTONDOWN, and its cousins (WM_RBUTTONDOWN, etc.) for detecting the left, right, or center mouse but- 
ton being pressed or released. 
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Common Mouse Messages 


When you move the mouse, Windows sends a WM_MOUSEMOVE message. The message is not sent every time the 
mouse cursor moves from one screen pixel to the next. How often the message is sent depends on how fast a computer 
is running Windows. In general terms, you can expect to get this message about every tenth pixel as the user sweeps 
the mouse cursor across the screen, more often if the cursor is moved slowly. 

- When your program receives a WM_MOUSEMOVE message, the /Param value contains the cursor’s X,Y position 
on the screen. The Y position is the high-order 16 bits, while the X position is in the low-order 16. Extracting the two 
WORD-sized values from a LONG parameter is such a common task that the WINDOWS.H file provides the LOWORD 
and HIWORD macros to automate the task. A typical program fragment for dealing with WM_MOUSEMOVE messages 
in the WinProc() function is 


; Long FAR PASCAL WndProc (CHWND hWnd, unsigned iMessage, WORD WParam, LONG lParam) 

. int nXpos, nYpos p 

switch (iMessage) , : /* process windows paseaabe xf 
: ' case WM_MOUSEMOVE: 


nXpos = LOWORD (lParam) ; 
nYpos = HIWORD (lParam) ; 


‘ 

;. Note that the mouse cursor position is given relative to the upper left corner of the window's client area. Windows 
provides two functions for converting back and forth between screen and client coordinates: ScreenToClient() and 
ClientToScreen(). These functions are often used as part of the mouse message processing logic. The other basic set 
of messages have to do with pressing and releasing the mouse button(s). Windows supports one, two, and three button 
mice, but provides no method to determine which type is in use. In practice, most programmers assume the conserva- 
tive case and only use the left mouse button. The messages passed to your program from the mouse button.active 


inside the program’s client area are summarized in Table 6-1. 


n__-Pressed = Released Pressed a Second Tim 
“Set WMLLBUTTONDOWN —_-WM_LBUTTONUP W_LBUTTONDBLCLK 
“Middle WM_MBUTTONDOWN WM_MBUTTONUP WM_MBUTTONDBLCLK 
Bottom WM_RBUTTONDOWN. WM_RBUTTONUP =» WM_RBUTTONDBLCLK 


Table 6-1. Client Avot Mouse Button Messages. ae 


You will not normally use them, but there is a parallel set of messages that are sent for mouse button activity 
outside of the program’s client area. These messages have the homolog names such as WM_NCLBUTTONDOWN, etc., 
where “NC” stands for “Nonclient.” Double-clicking the mouse will not automatically generate a double-click mes- 
sage. You must specify that you want these messages in the window’s class deéfinition. This involves adding the 
CS_DBLCLKS value to the class style as shown here. | 

wndclass.style = CS_HREDRAW | CS_VREDRAW | CS_DBLCLKS ; 


This would be a typical setting prior to calling RegisterClass(). All of the mouse button messages return the.X and 
Y coordinates of the cursor in the Param parameter, just like WM_MOUSEMOVE. They also use wParam encodes if 
one of the other mouse buttons, or the shift or control keys, are down when the specified mouse button is pressed. The 
full descriptions of the messages are given in Chapter 9, Windows Messages. 
You can find out if the system has a mouse by calling 
bMouse = GetSystemMetrics (SM_MOUSEPRESENT) ; 


The function will return TRUE if there is a mouse, FALSE if not. You can provide an imitation itn mouse control by 
converting from keyboard cursor keypresses to mouse movements. The SetCursorPos() function allows direct control 
of the cursor location without reference to a mouse. There is no direct way to find out out how many buttons the 
system mouse has. - : 
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Caution: The mouse is a shared resource between all running programs under Windows. Some of the mouse 
control functions, such as GetCapture() and SetNoubleClickTime(), will affect all of the programs running. Care must 
be taken to free the mouse, and return the system parameters to their original state, as quickly as possible. 


Mouse Functions 

The most frequently used mouse function is LoadCursor. It either loads one of the predefined cursor shapes or allows 
you to load a custom cursor created with the SDKPaint program. Custom cursors have to be referenced in the 
program’s resource .RC file and given a name. For example, to load the cursor file HAND.CUR created with SDKPaint 
and give the resulting cursor shape the name “hand,” add the following line to the resource file 


hand CURSOR hand.cur 


The cursor shape can be attached to a window's class definition. Windows then switches to that cursor shape any 
time the mouse cursor is within the window’s client area. The function LoadCursor() does the work of pulling the 
cursor out of the resource data so that it can be attached to the class definition. Use a statement like 


wndclass.hCursor = LoadCursor (ghInstance, “hand") ; 

prior to using RegisterClass() to create the class definition. If you plan to switch between cursor shapes within the 
bounds of one window, you are better off not assigning a cursor to the window's class. In this case, set the class cursor 
to NULL, as shown here. 

wndclass.hCursor = NULL: 


Then you can turn on the right cursor shape as the program receives WM_SETCURSOR . A typical code fragment 
for a program that uses two cursors would be 


tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : 


static HCURSOR hHandCursor, hArrowCursor ; 

static BOOL bUseHand = FALSE ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_.CREATE: 
hArrowCursor = LoadCursor (NULL, IDC_ARROW) ; 
hHandCursor = LoadCursor (ghInstance, (LPSTR) “hand") ; 
break ; ‘ : 
case WM_SETCURSOR: 
if (bUseHand) 
SetCursor (hHandCursor) ; 
else 
SetCursor (hArrowCursor) ; 
break ; 


[Other program lines] 


The ultimate cursor shape control is the CreateCursor() function, added with the 3.0 version of Windows. This 
function allows you to change the shape of the cursor as the program runs, or as thé mouse moves. It can be used to 
create a cursor that shows the numeric values of the cursor position as the mouse moves. Other creative uses are 
possible. CreateCursor() defines a cursor with two memory areas that contain bitmaps of the cursor shape. The 
_ bitmaps are combined using logical AND and XOR operations to provide black, white, transparent, and inverse screen 
coloring on every pixel of the cursor. 


Caret Functions 


The caret is a blinking line or object that marks a temporary location on the screen. It is used in word processing 
applications to mark where the next typed letter will be displayed. Similar uses appear in music score programs. The 
caret automatically appears in edit controls (created with CreateWindow()). Carets inside edit controls do not have 
to be controlled by your program, as the edit control has all of the built-in logic for moving the caret. The caret is a 
system global resource. This means that there can only be one caret visible on the screen, no matter how many 
windows or edit controls are visible. If you open a new window and it displays a caret, any other caret on the screen 
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will vanish. This is logical, as otherwise the user would not be able to tell where the next keyboard input would end up. 
Carets are manipulated as static objects. They do not send messages back to windows. Generally, carets are defined 
(using CreateCaret()) as vertical lines, although they can be bitmap images. Windows provides support for moving the 
caret, changing its blinking speed, and hiding it when not needed. If you use a caret in an application, you will need to 
process the WM_SETFOCUS and WM_KILLFOCUS messages. When the application gains the input focus, create and 
show the caret using CreateCaret() and ShowCaret(). When it loses the input focus, call DestroyCaret() to eliminate 
it. There is an example of this logic under the CreateCaret() function description. 


Mouse and Cursor Function Summaries 
Table 6-2 summarizes the mouse and cursor functions. The complete function descriptions are after the table. 


ClientToScreen 


Purpose 


Converts a point from client coordinates to screen coordinates. 


ClipCursor Confines the mouse cursor to an area on the screen. 
CreateCaret Creates a caret shape. . 
CreateCursor Builds a cursor shape. 

DestroyCaret Removes a caret from a window. 

DestroyCursor Deletes a cursor created with CreateCursor(). 

GetCapture Retrieves a handle to the window that has captured the mouse. 
GetCaretBlinkTime Finds the current rate at which the caret is flashing. 
GetCaretPos Determines the location of the caret in a window's client area. 
GetClipCursor Determines the rectangle that the mouse was last confined to by ClipBursor(). (Win 3.1) 
GetCursorPos Retrieves the X,Y position of the mouse cursor. 
GetDoubleClickTime Retrieves the double-click time value for the mouse. 

HideCaret Makes a caret invisible. 

LoadCursor Loads a new cursor shape. 

ReleaseCapture Releases capture of the mouse. 


ScreenToClient 


Converts from screen coordinates to client window coordinates. 


SetCapture Captures the mouse so that only the program with the mouse captured receives mouse messages. 
SetCaretBlinkTime Sets the rate at which: the caret shape flashes on the screen. 

SetCaretPos Sets the position of the caret. . 

SetCursor Establishes which cursor shape to display. 

SetCursorPos Moves the mouse cursor to a new location. 

SetDoubleClickTime Changes the mouse button double-click time. 

ShowCaret Makes the caret visible at its current location. 

ShowCursor Shows or hides the cursor shape. 

SwapMouseButton Reverses the right and left mouse buttons. 


Table 6-2. Mouse and Cursor Function Summaries. 
CLIENTTOSCREEN ge Win2.0 mWin30 mWin3.1 


Purpose ' Converts a point from client coordinates to screen coordinates. 
Syntax void ClientToScreen(HWND hWnd, LPPOINT [pPoint); 
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Description 


Uses 
Returns 
See Also 


Parameters 
hWnd 


lpPoint 


Related Messages 
Example 
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The point structure pointed to by /pPoint is updated using screen coordinates. Screen coordi- 
nates are pixels measured from the upper left corner of the screen. Client coordinates are pixels 
measured from the upper left corner of the window's client area. 


Use in programs that use the mouse to capture images off of the screen. _ 
No returned value (void). 
SetCapture(), SereenToClient() 


HWND: The parent window's handle. 


LPPOINT: A long pointer to a point structure. Initially, this point contains the client point coor- 
dinates. 


WM_LBUTYONDOWN, WM_MOUSEMOVE 
Here is a useful function which you can use in screen capture programs. The function takes two 
points in client coordinates (as might be retrieved from the [Param data from a WM_LBUTTON- 


DOWN message) and converts them to window coordinates. The function then draws a rectangle 
onto the screen, outlining an area between the two points, 


/* OutlineBlock() writes a rectangle on the screen given the two corner */ 
/* points. The R2_NOT style is used, so drawing twice on the same location */ 
/* erases the outline. */ 


void OutlineBlock (HWND hWnd, POINT beg, POINT end) 


{ 
HDC hDC ; 
hDC = Createpc < "DISPLAY", NULL, NULL, NULL) ; 
ClientToScreen (hWnd, &beg) ; /* convert to screen units */ 
ClientToScreen (hWnd, 8end) ; 
SetROP2 ChDC, R2_NOT) ; /* use Logical NOT brush */ 
MoveTo ChDC, beg.x, beg.y).; /* draw rectangle */ 
LineTo ChDC, end.x, beg.y) ; 
LineTo (hDC, end.x, end.y) ; 
LineTo (hO0C, beg.x, end.y) ; 
LineTo (hDC, beg.x, beg.y) ; 
DeleteDC ChDC) ; ; 

} 

CrrpCursor @Win2.0 weWin3.0 Win 3.1. 

Purpose  Confines the mouse cursor to an area on the screen. 

Syntax void ClipCursor(LPRECT [pRect); 

Description After calling this function, the mouse pointer can on be moved within the bounds set by the 
lpRect rectangle. 

Uses Use sparingly, if at all. If the mouse are are set in a program, they will continue to be in effect 
after the program terminates. This basically makes the mouse useless, forcing the user to reboot 
the computer. A better way for a program to limit mouse’s activities is with GetCapture(). 

Returns © No returned value (void). 

See Also GetCapture(), SetCursor(), GetClipCursor(). 

Parameters © : 2 

lpRect LPRECT: A long pointer to a rectangle structure. Use SetRect() to quickly fill in the rectangle’s 

dimensions. Set [pRect equal to NULL to free the mouse to move anywhere on the screen.’ 

Related Messages WM_MOUSEMOVE . 
When the user clicks the “Do It!” menu item,.the mouse is confined to a region bounded by a 


Example 
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rectangle with screen coordinates 10,10 and 200,200. The program frees the mouse when the user 
clicks the “Quit” menu item. 


“Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
t , 


-RECT rMouseCage ; 
switch (iMessage) /* process windows messages */ 
{ : 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
SetRect (C(LPRECT) &rMouseCage, 10, 10, 200, 200) ; 
ELAR EUR SOF (CLPRECT). &rMouseCage) ; /* trap mouse */ 
break ; 
case IDM_QUIT: j 
ClipCursor (NULL) ; /* Let the mouse loose again */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, (Param) ; 
} ies 
return (OL) ; 
} 
CREATECARET wWin2.0 mWin30 mWin3.1 
Purpose Creates acaret shape. _ 
Syntax void CreateCaret(HWND hWnd, HBITMAP hBitmap, int nWidth, int nHeight), 
Description Only one caret can exist for any window at a given time. This function creates a caret, removing 
any existing caret. The caret can either be a bitmap or a vertical line of set size. 
Uses The first step in displaying a caret. This function is followed by SetCaretPos() and ShowCaret(). 
Returns No returned value (void). 
See Also DestroyCaret(), SetCaretPos(), ShowCaret(), LoadBitmap() 
Parameters 
hWnd HWND: A handle to the window that owns the caret. 
hBitmap HBITMAP: A handle to the bitmap to use as the caret. The handle is obtained using the 
LoadBitmap() function. hBitmap can be NULL. In this case, a black caret nWidth wide by 
nHeight tall is constructed. If hBitmap is 1, a gray caret is created. 
nWidth © int: The width of the caret in logical units. The size will depend on the mapping mode in effect. 
Ignored if hBitmap is not NULL. Set to NULL to use the default width, equal to the window 
border width. ' 
nHeight int: The height of the caret in logical units. The size will depend on the mapping mode in effect. 
Ignored if hBitmap is not NULL. Set to NULL to use the default height, a multiple of the window 
border width. 
Related Message WM_SETFOCUS, WM_KILLFOCUS ; : 
Example This example shows the creation of two carets. The first is created when the program starts. This 


is a black cursor, 3 pixels wide by 20 high. When the user clicks the “Do It!” menu item, a bitmap 
caret i is loaded and displayed. 
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C> The Resource .RC File 


/*®* generic.rc */ 
H#Hinclude <windows.h> 
Hinclude “generic.h" 


generic ICON generic.ico 
ibeam BITMAP ibeam.bmp 
generic MENU 
BEGIN 
MENUITEM “&Do It!" IDM_DOIT 
MENUITEM "SQuit", IDM_QUIT 
END 


The program’s WndProc() function uses a static variable bNewCaret to keep track of which caret to display. The 
caret shape is created when the application gains the input focus and is destroyed when the focus is lost. Note how the 
caret is hidden before painting (WM_PAINT message) and then displayed again. This avoids having the caret nbnee 
interfere with the painting of the client area. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : : 


static HBITMAP hbmCursor ; 

PAINTSTRUCT ps ; 

static BOOL bNewCaret = FALSE ; 

switch (iMessage) /* process windows messages */ 


case WM_SETFOCUS: 
if (bNewCaret) 


{ 
hbmCursor = LoadBitmap (ghInstance, (LPSTR)"ibeam") ; 
CreateCaret (hWnd, hbmCursor, NULL, NULL) ; 

} 

else 


CreateCaret (hWnd, NULL, 3, 20) ; 
SetCaretPos (10, 10) ; 
ShowCaret (hWnd) ; 
break ; 
case WM_KILLFOCUS: 
DestroyCaret () ; 
break ; 
case WM_PAINT: 
HideCaret (hWnd) ; 
BeginPaint (hWnd, &ps) ; 
TextOut (ps.hdc, 10, 10, "Text output.", 12) ; 
EndPaint (hWnd, &ps) ; 
shoucaret ChWnd) ; 


break ; 
case WM_| COMMAND : /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* Change caret shapes */ 
- bNewCaret = TRUE ; 
PostMessage (hwnd, WM_SETFOCUS, 0, OL) ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
} : 
break ; 
case WM_DESTROY: /* stop application */ 


DeleteObject ChbmCursor) ; 
PostQuitMessage (0) ; 
break ; 


default: i ' /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
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} 
return (OL) ; 
} 
CREATECURSOR OWin2.0 @Win80 mWin3.t 
_ Purpose Builds a cursor shape. : . 
_ Syntax HCURSOR CreateCursor(HANDLE hInstance, int nXhotspot, int sae fie int nWidth, int 
nHeight, LPSTR lpANDbitPlane, LPSTR lpXORbitPlane); 
Description This function allows you to create a mouse cursor shape while the program is running. The cursor 


shape is controlled by two memory areas that contain masks for the cursor. The bits in these 


’ memory blocks are compared to the screen pixels using a logical AND and Hpgteat exclusive OR 


operations. The results are shown in Table 6-3. 


0 
0 
1 
1 


Table 6-3. Cursor Boolean Masks. 
-Usés 


Returns 
See Also 


Parameters 
‘hinstance 


nXhotspot 
nYhotspot 
nWidth 


nHeight © 
lpANDbitPlane 


lpXORbitPlane 


Related Messages 


Example 


Black 


0 

1 White 

0 Transparent _ 
1 Inverted color 


Modifying a cursor shape as the program runs. The cursor can be made to change depending on 
where it is on the screen, or what action is occurring. 


A handle to the cursor created, NULL on error. 
LoadCursor(), DestroyCursor(), SetCursor() 


HANDLE: The instance handle for the running program. 


int: The horizontal position on the cursor’s reclanee that i is logically the point with which the - 
cursor points. 


int: The vertical position on the cursor’s rectangle that is logically the point with which the 
cursor points. ant 


int: The width of the cursor bitmap in pixels. 
int: The height of the cursor bitmap in pixels. 


LPSTR: A pointer to the memory area containing the AND mask for the cursor. The Microsoft 
mouse documentation calls this the “screen mask.” See Table 6-3 for the meaning of the AND 
mask bits. 


LPSTR: A pointer to the memory area containing the XOR mask for the cursor. The Microsoft 
mouse documentation calls this the “cursor mask.” See Table 6-3 for the meaning of the AND 
mask bits. . , 


WM_MOUSEMOVE, WM_SETCURSOR 


This example uses CreateCursor() to build a rectangular cursor shape filled with a gray pattern. 
When the user clicks the “Do It!” menu item, the cursor shape is modified by drawing anX on the 
gray background. The cursor shape is only active in the window’s client area. The normal arrow 
cursor is displayed in the menu, title, and borders of the window, as well as outside of the 
application’s window area. The example takes a shortcut to fill in the background. The cursor 
data is actually loaded from a bitmap. The bitmap is painted with the stock object . 


“ “LTGRAY_BRUSH" to come up with the gray pattern. This saves having to figure out how to set: 
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each of the memory bits in the areas that CreateCursor() looks to find the cursor shape data. 
Similarly, the X is drawn on the bitmap image and then loaded into the cursor memory area. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 


static 
static 
static 
HoC 
static 
static 
LPSTR 


HCURSOR hCursor 
int 
HBITMAP hBM ; 


HDC 
HANDLE 


switch CiMessage) 


{ 


case WM_CREATE: 


nCursX = GetSystemMetrics CSM_CXCURSOR) 
nCursY = GetSystemMetrics (SM_CYCURSOR) 
hBM = CreateBitmap (nCursX, nCursY, 1, 1, 


’ 


nCursX, nCursY, nByteArea ; 


hoc ; 


hDCBitmap ; 


hmemAND, 


hmemXOR ; 


LpAND, LpXOR ; 


hDC = GetDC (hWnd) ; 
hDCBitmap = CreateCompatibleDC C(hDC) ; /* get bitmap DC */ 


ReleaseDC ChWnd, 


hdc) ; 


/* process windows messages */ 


a /* get curs size */ 
7 


NULL) ; 


nByteArea = (nCursX/8) * nCursyY ; 
SelectObject (hDCBitmap, hBM) ; 
/* reserve memory for cursor shape data */ 


hmemAND 
hmemXOR 


LpAND 
LpxXOR 


GetBitmapBits ChBM, 


GlobalAlloc (GMEM_MOVEABLE, (DWORD) nByteArea) ; 
GlobalALloc (GMEM_MOVEABLE, (DWORD) nByteArea) ; 


/* lock the memory areas to work with them */ 


GlobalLock ChmemAND) ; / ‘ 
GlobatLock ChmemXOR) ; 


/* create a gray wectanate cursor */ 
SelectObject (hDCBitmap, GetStockObject (LTGRAY_BRUSH)) ; 
PatBlt (hDCBitmap, 0, 0, nCursX, nCursY, PATCOPY) ; 


CDWORD) nByteArea, LpAND) ; /* in mem */ 


_fmemset (LpxOR, 0, nByteArea) ; /* XOR mem to all O's */ 


GlobalUnlock ChmemAND) ; 
GlobalUnlock ChmemXOR) ; 


break ; 
case WM_MOUSEMOVE: 


/* draw the custom cursor */ oe 


SetCursor (NULL) ; 


if (hCursor) 


DestroyCursor (hCursor) ;/* kill old cursor, if any */ 


LpAND = Globaltock (hmemAND) ; 
LpXOR = GlobalLock ChmemXOR) ; 
hCursor = CreateCursor (ghInstance, 0, 0, nCursXx, . x. 


nCursY, 


break ; 
case WM_COMMAND: 
switch (wParam) 
{ 
case IDM_DOIT: 
LpAND = 


break ; 
case IDM_QUIT: 


LpAND, LpXOR) ; Me 
GlobalUnlock (hmemAND) ; 
GlobalUnlock ChmemXOR) ; 
SetCursor C(hCursor) ; 


/*®* process menu items */ 


/* add an X to the cursor bitmap */ 
GlobalLock (hmemAND) ; 

SelectObject (hDCBitmap, Bets cockobiect (BLACK_|! PEN)) ; 
MoveTo (hDCBitmap, 0, 0) ; 

LineTo ChDCBitmap, ncursX, nCursyY) ; 

MoveTo (hDCBitmap, 0, nCursY) ; 

LineTo (hDCBitmap, nCursX, QO) ; 

GetBitmapBits (hBM, somone? nByteArea, LpAND) ; 
Stoballnbock ChmemAND) ; 


DestroyWindow Chind) ; 


break ; 
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break ; 
case WM_| DESTROY: /* stop application */ 
DestroyCursor (hCursor) ; 
DeleteObject ChBM) > 
DeleteDC (hDCBitmap) ; 
“GlobalFree ChmemAND) ; 
GlobalFree ChmemXOR) ; | 
PostQuitMessage (0) ; 


break ; . : 
default: , /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, (Param) ; 
} ae : 
return COL) ; 
>. 
DestroyCareET | mWin20 mWin3.0 mWin3.1 
Purpose Removes a caret from a window. . 
Syntax void DestroyCaret(void); 
Description Used to destroy cursors created with the CreateCaret() function. Frees any memory associated 
with the caret, but does not eliminate a bitmap if it was used to create the caret. 
Uses Permanent removal of a caret. Use HideCaret() and ShowCaret() for temporary hiding and dis- 
playing of the caret. This function will only work if the current task (running application) owns 
the caret. 
Returns _ No returned value Ga 
See Also ShowCaret(), HideCaret(), CreateCaret(), DeleteObject() 
Parameters None (void). 


Related Messages WM_SETFOCUS, WM_KILLFOCUS 


Example See the example under the CreateCaret() function description. 
DeEstroyCursor OWin2.0 mWin30 mWin3.1 
Purpose Deletes a cursor created with CreateCursor(). 
Syntax BOOL DestroyCursor(HCURSOR hCursor); | | 
Description Frees the memory associated with a cursor created with CreateCursor(). Do not a this with 
cursors loaded from the program’s resource .RC file. Also, do not forget to delete the ::*:--: objects 
. used to create the cursor (see the example under CreateCursor()). 
Returns BOOL. TRUE if the cursor was destroyed, FALSE on error. 
See Also CreateCursor(), DeleteObject() . 
Parameters 
hCursecr HCURSOR: A handle the cursor created with CreateCursor(). 
Example See the example under the CreateCursor() function description. 
GETCAPTURE wWin2.0 mWin3.0 8 Win31 
Purpose Retrieves a handle to the Sindow that has captured the mouse. 
Syntax HWND GetCapture(void); 
. Description Once a window captures the mouse, no other application will receive messages from the mouse. 
GetCapture() allows you to find out which window has captured the mouse. 
Uses Capturing the mouse is normally used in applications that use the mouse to outline or store 


images off of the screen. GetCapture() can be used to locate the window that has the mouse 
captive, so that you can send that window a message to release the mouse. 
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See Also 


Parameters 
Related Messages 


Example 
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HWND, the handle of the window that has captured the mouse. NULL if no window has captured 
the mouse. 


SetCapture(), ReleaseCapture() 

None (void). 

WM_MOUSEMOVE | 
This example prints the name of the window with the mouse captured on the window’s client area 

every time the window receives a WM_MOUSEMOVE message. When the user clicks the “Do It!” 

menu item, the program captures the mouse itself. Clicking the left mouse button releases the 

mouse. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC 
HWND 
char 


hoc ; 
hwndCapture ; 
cBuf [25] ; 


switch (iMessage) /* process windows messages */ 


{ 


3 
} 


case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
SetCapture (hWnd) ; 
break ; 
case IDM_QUIT: /* send end ot application message */ 
DestroyWiadow ChWnd) ; 
; break ; 
} 
break ; 
case WM_MOUSEMOVE: 
hwndCapture = Sec capture ©); 
hDC = GetDC (hWnd) ; 
TextOut (hdc, 10, 10, 
"The vando with the mouse captured is:", 38) ; 
if ('hwndCapture) 
TextOut (hDC,-10, 40, "<None>", 6) ; 
else 
{ , . 
GetWindowText (hwndCapture, cBuf, 24) ; 
TextOut (hDC, 10, 40, cBuf, strlen (cBuf) ) ; 
} 
ReleaseDC (hWnd, hDC) ; 
break ; 
case WM_LBUTTONDOWN: 
ReleaseCapture () ; 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 3 ? ; 
default: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


GeTCARETBLINKTIME mWin2.0  mwWin3.0 wm Win3.1 


Purpose 
Syntax 
Description 


Returns 


Finds the current rate at which the caret is ‘lashing 
WORD GetCaretBlinkTime(void); 


Returns the time, in milliseconds, een flashes of the caret. The time i is returned even if the 
caret is not visible. 


WORD, the time in milliseconds between flashes. 
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See Also SetCaretBlinkTime(), CreateCaret() 
Parameters _— None (void). . | 
Example In this example, the blink rate of the caret is slowed down by 0.1 sec every time the user clicks the 


“Do It!” menu item. The blink rate is restored to 0.5 sec (500 milliseconds) when the user clicks 
the “Quit” menu item and exits the program. This example is interesting if two instances of the 
program are run at the same time. Starting a second copy steals the caret from the first program’s 
client area. Clicking the “Do It!” menu item in either instance of the program slows the blink rate 

_ inthe window that displays it. The changed blinking rate remains in effect in any application that 
gains the caret. This visually demonstrates that the caret i is a Shared resource between applica- 
tions and instances. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


{ 


PAINTSTRUCT ; ps ; 

static BOOL bNewCaret = FALSE ; 

int — nTime ; 

switch (iMessage) /* process windows messages */ 


case WM_SETFOCUS: 
CreateCaret (hWnd, NULL, 3, 20) ; 
SetCaretPos (10, 10) ; 
ShowCaret (hWnd) ; 
break ; 
case WM_KILLFOCUS: 
DestroyCaret () ; 
- break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) : 
t 
case IDM_DOIT: /* Change caret blink time */ 
aTime = GetCaretBlinkTime () ; 
nTime += 50 ; 
SetCaretBlinkTime (nTime) ; 
break ; % 
case IDM_QUIT: /* send end of applicatton message */ 
DestroyWindow ChWnd) ; 


; break ; 
} 
break ; 
case WM_DESTROY: a stop application */ 
SetCaretBlinkTime e200 /* normal blink time*/ 
PostQuitMessage (Q) ; 
. break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
} 
return (OL) ; 
} 
GetCarETPos : Win2.0 wWin3.0 mWin31 
Purpose Determines the location of the caret in a window’s client area. 
Syntax void GetCaretPos(LPPOINT lpPoint); . 
Description The current X and Y positions are loaded into the POINT seencuits pointed to by [pPoint. The 
program should be sure to use ShowCaret() before using this function. Otherwise, the location 
returned will be in whatever window currently displays the caret. 
Returns No returned value (void). 
See Also SetCaretPos(), CreateCaret() 
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Parameters 
lpPoint 


Example 
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LPPOINT: A pointer to a point structure that will hold the caret’s.X and Y client coordinates. The’, 
values are given in logical units. 


In this example, the caret is moved 10 units to the right every time the user clicks the “Do It!” 
menu item. The current caret position is also displayed on the client area. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


{ 
POINT ptCaretPos ; 
char cBuf £10] ; 
HDC hDC ; 
switch (iMessage) /* process windows messages */ 
case WM_CREATE: 
CreateCaret (hWnd, NULL, 3, 20) ; 
SetCaretPos (10, 10) ; 
ShowCaret (hWnd) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
case IDM_DOIT: /* User hit the “Do it" menu item */ 
GetCaretPos ((LPPOINT) &ptCaretPos) ;— 
SetCaretPos (ptCaretPos.x + 10, ptCaretPos. as I 
itoa (ptCaretPos.x + 10, cBuf, +0) : 
hDC = GetDC ChWnd) ; 
TextOut ChDC, 10, 50, cBuf, Zepben CeBuf)) ; 
TextOut (hdc, 10, 80, 
"= current caret X position.", 27) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
; break ; 
} 
break.; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
“ return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 

} 

GETCiipCursor — OWin2.0 OWin30 mWin3t 

Purpose Determines the rectangle that the mouse was last confined to by ClipCursor(). 

Syntax void GetClipCursor (LPRECT /pRect); . . 

Description ClipCursor() is used to limit the mouse cursor to a rectangular area on the screen. 
GetClipCursor() can be used to determine the current clipping rectangle. 

Uses Seldom used. The cursor is a shared resource between all applications running on the system. 
Limiting the cursor to an area on the screen violates the Windows design principle of allowing 
programs to behave independently. 

Returns No returned value (void). 

See Also ClipCursor(), GetWindowRect() 

Parameters 

IpRect ‘LPRECT: A pointer to a RECT data structure. GetClipCursor() will fill in the four rectangle 


coordinate values for the current mouse clipping rectangle. If the mouse is not confined, the 
screen dimensions are retrieved. ; 
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- Example This example, illustrated in Figure 
6-2, confines the mouse cursor tO gure —— — 
the limits of the application's win-  [EingauuaammEnmn Col od ¢ | [~ Ss 
dow. The rectangle is recalculated . 
when either 2 WM_MOVE or Do tt! Quit 
WM_SIZE message is received. The Mouse cage = [22, 22, 262, 120] 
coordinates of the clipping rect- 
angle are displayed in the client 
area. Clicking the “Do It!” menu — 
item temporarily removes the Figure 6-2. GetClipCursor() Example. 
mouse limits. 


long FAR PASCAL WndProc C(HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ - 


RECT rCage ; 

PAINTSTRUCT ps ; 

char cBuf C128] ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_MOVE: 
case WM_ SIZE: 
GetWindowRect (hWnd, &rCage) > 


ClipCursor (CLPRECT) &rCage) ; /* trap mouse in window */ 
InvalidateRect (hWnd, NULL, TRUE) /* force paint */ 
break ; 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
GetClipCursor (&rCage) ; 
TextOut (ps.hdc, 0, 0, cBuf, wsprintf (cBuf, 
“Mouse cage = (id, 4d, “%~d, %d1", 
rCage. left, PCages 0p, rCage.right, rCage.bottom)) ; 
EndPaint ChWnd, &ps) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: 
ClipCursor (NULL) ; /* free mouse */ 
break ; ° 


case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
break ; 
case WM_DESTROY: , 
ClipCursor (NULL) ; /* free mouse */ 
PostQuitMessage (0) ; . 
break ; 
default: 4 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (QL) ; 
} 
GeTCursorPos mWin2.0 mWin30 mWin3.1 
Purpose Retrieves the. X, Y position of the mouse cursor. 
Syntax void GetCursorPos(LPPOINT [pPoint); — 
Description | The.X,Y position of the mouse cursor isloaded into the /pPoint structure. Screen coordinates are 


used. To conver: to client coordinates use, ScreenToClient(). 


u 
; “s 
¥ 


a : F PA | 
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Uses 


Returns 
See Also 


Parameters 
lpPoint 


Related Messages 
Example 


6. MOUSE AND CURSOR FUNCTIONS ¥ 


Any time you need to locate the 
mouse cursor. This is seldom neces- 
sary, aS moving the mouse generates 
WM_MOUSEMOVE messages, and a 

clicking the mouse buttons gener- Do ttt Qu it 

ates WM_LBUTTONDOWN, etc. Cursor X = 4892. ¥ = 406 

Messages. These messages encode ‘ 
the cursor position in the /Param 
value (Chapter 9, Windows Mes- Figure 6-3. GetCursorPos() Example. 

sages, includes all of the message 

descriptions). 


No returned value (void). 
SetCursorPos(), ScreenToClient(), SetCapture(), ReleaseCapture() 


generic ~ [ 


LPPOINT: A pointer to a POINT structure. 
WM_MOUSEMOVE - . 


When the user clicks the “Do It!” menu item, a timer is set. WM_TIMER messages are sent every 
second, causing the cursor position to be displayed on the screen at these time intervals. (See 
Figure 6-3.) This updating continues even if the window loses the input focus to another applica- 
tion. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
£ 


HDC 
POINT 
char 


switch 


} 
return (OL) ; 


hoe ; 
pCursor ;° 
cBuf £128] ; 


CiMessage) /* process windows messages */ 


case WM_TIMER: 
GetCursorPos (&pCursor) 
hDC = GetDC (hWnd) ; 
SetBkMode (hDC, OPAQUE) ; 
TextOut (hoc, 0, 0, cBuf, wsprintf (cBuf, 
“Cursor X.= 4d, Y = 4d “, pCursor.x, pCursor.y)) ; 
ReleaseDC ChWnd, hDC) ; 


“se 


break ; a ea 
case WM_COMMAND: /* process menu items */ 

switch (wParam) 

{ 

case IDM_DOIT: /* set 1 sec timer */ 


if C!SetTimer (hWnd, 1,:1000, NULL)) 
MessageBox (hind, "Too many clocks or timers!", 
“Warning”, MB_ICONEXCLAMATION | MB OK) ; 


break ; 
case IDM_QUIT: /* send end of application message */ 
Destroy@indou ChWnd) ; 
break ; 
}. 
break ; - 
case WM_DESTROY: /* stop application */ 


KillTimer ChWnd, 1) ; 

PostQuitMessage (0) ; 

break ; 
defaults: /* default windows message processing bald 
return DefWindowProc (hwnd, iMessage, wParam, (Param) ; 
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GerDousreCuck Time ets Win2.0 wWin3.0 mWin3l 
Purpose | . Retrieves the double-click time value for the mouse. . 
- Syntax - WORD GetDoubleClickTime(void); . 
Description The double-click time is the number of milliseconds between two m mouse clicks. Clicking faster than 
4 this value generates a. WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, or WM_RBUT- 
TONDBLCLK message for the left, middle, or right mouse buttons, respectively. Note that the 
WM_LBUTTONDOWN, etc. messages will always be received prior to othing the double- click 
‘message. ; 
Uses Used in advance of SetDoubleClickTime() to find the current double-click time value, prior to — 
changing it. 
Returns WORD, the double-click time in milliseconds. 
See Also SetDoubleClickTime(). 
Parameters None (void). 
Related Messages WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, WM _RBUTTONDBLCLK . 
Note The double-click messages will only be generated if the os DBLCLKS style is added to the 
window's class definition (see the example). 
Example This program ‘detects right button single- and double- clicks and ‘prints ‘ieesaueed in the client 


area for each. The messages are erased by overwriting them with blanks when WM_MOUSEMOVE 
messages are received. Clicking the “Do It!” menu item increases the double-click time by 100 
milliseconds, after displaying the current double-click time. Receiving double-clicks requires that 
the CS_DBLCLKS style be added to the window’s class definition i in the wan function 


wndclass.style = CS_HREDRAW | CS_VREDRAW | CS_DBLCLKS ; 


long FAR PASCAL 
{ 
HDC 
char 
int 
static: 


Switch 
{ 


Note that the doube-click time is reset to the original timing when the program exits. Other- 
wise the slower pouble: click time would continue to affect all of the other programs on the 
system. 


WndProc CHWND hWnd, unsigned ineecages WORD wParam, LONG lParam) 


hoc 7. 
cBuf: C25] ; 
nDoubleTime ; 
int NOLADCLick ; 
CiMessage) /* process windows messages */ 


‘case WM_CREATE: 
nOldDClick = GetDoubleClickTime O; 
break ; 


case WM_ COMMAND: e oa /* process menu items */ 


switch (wParam) 
a § 

case IDM _DoIT: 
nDoubleTime = GetDoublecl ickTime ); 
hDC = GetDC ChWnd) ; 
TextOut (hDC, 10, 10, "The poubrs Click Time =", 23) ; 
jtoa (nDoubleTime, cBuf, 10) ; 
TextOut (hDC, 200, 10, eBut, ae CcBuf)) j 
ReleaseDC hWnd, hDC) ; 
SetDoubleClickTime CnDoubLeTine + 100) ; 
break ; 

case IDM |_ QUIT: '/* send end of application message */ 
Destroy windos ChWnd) ; 
break >; 


break ; 
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case WM_MOUSEMOVE: _ . /* writes over old messages as mouse moves */ 
hDC = GetDC (hWnd) ; 
SetBkMode (hDC, OPAQUE) ; : 
TextOut (hDC, 10, 30, " toe, ", 30); 


TextOut (hDC, 10, 50, ". ", 30); 
ReleaseDC ChWnd, hDC) ; 
break ; : 

case WM_LBUTTONDOWN: /* detected the Left mouse button down */ 


hDC = GetDC ChWnd) ; 
TextOut (hDC, 10, 30, “sot a left button!", 17) ; 
Releasebe (hWnd, hDC) ; : 
break ; 
case WM_LBUTTONDBLCLK: /* Oetected a double click oe left button */ 
hDC = GetDC ChWnd) ; : : 
TextOut (hDC, 10, 50, "Got a double click!", 18) ; 
Releasedt Chund,_ hDC) ; 
break ; 
case WM_DESTROY: /* stop application */ 
SetDoubleClickTime (nOLdDCLick) ; 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


HmeCARET 


Purpose 
Syntax 
Description 


Uses + 


Returns 
See Also 


Parameters 
hWnd 


Example a 


LoapCursor 
Purpose 

Syntax 
Description 


mWin2.0 mWin30 mWin3.1 
Makes a caret invisible. 
void HideCaret(HWND hWnd); 
The caret must be created with CreateCaret() before it can be visible. As soon as ShowCaret() is 
called, the caret starts blinking. The caret remains visible until HideCaret() or DestroyCaret() is 


called. If HideCaret() has been called more than once, an equal number of ShowCaret() calls will 
be needed before the caret becomes visible. 


It is frequently desirable to hide the caret while the user is doing opabatlets that take the focus 
of activities away from the client area (menu selections, etc.), or during WM_PAINT processing. 
As soon as the activity is done, the caret can be made visible again with ShowCaret(). The caret 
is shared by all applications. If a caret is displayed on one program’ s window, a caret i in another 
running program’s window will disappear automatically. 

No returned value (void). 


ShowCaret(), DestroyCaret(), SetCaretBlinkTime() _ "ss = 


HWND: A handle for the window that owns the caret. A window can only own one caret at one 
time. Use CreateCaret() to add a caret shape to a window. Setting hWnd to NULL will hide the 
caret if any window in the current task owns the caret. 


See the example under the CreateCaret() function description. | 


Win.  @Win3.0  mWin3.l 
Loads a new cursor shape. oo 
HCURSOR LoadCursor(HANDLE instance, LPSTR lpCursorName); 


This function allows you to load predefined cursors that Window’s supplies, or a custom cursor 
designed with the SDKPaint program. For the latter, the cursor name is included in the resource 
.RC file. Cursors must be loaded prior to calling SetCursor() to make them visible. 
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Uses -_ If the cursor is loaded as part of the window's class definition, the mouse cursor will change to the 
loaded cursor shape any time the mouse is within the windows client area. If the goal is to have 
different cursor shapes within the same window's client area at different times, then the window 
class cursor shape should be set to NULL, and the cursor specified by calling SetCursor() every 
time a WM_SETCURSOR message is received. See the SetCursor() example code to see this in 


practice. 
Returns A handle to the new cursor. NULL if new cursor was found. 
See Also SetCursor(), CreateCursor() 
Parameters Mes R 
hInstance INSTANCE: The instance handle for the executable file that contains the cursor. hInstance 


should be NULL if you are loading one of the predefined cursor shapes listed below. 


lpCursorName LPSTR: A pointer to a string containing the cursor name. For custom cursors, this should be the 
name used to reference the cursor in the resource .RC file. For predefined cursors, where 
hInstance has been set to NULL, JpCursorName should be one of the values described in Table 6-4. 


Value Meaning © 

IDC_ARROW The standard arrow shape. 

IDC_CROSS A thin crosshair cursor. 

IDC_IBEAM An |-beam cursor. Used for positioning text. 

IDC_ICON An empty icon. 

IDC_SIZE A square with a smaller square in the lower right corner. Looks like a window being reduced in size. 


IDC_SIZENESW. The double-headed arrow Windows uses when adj sid the upper left and ae right sizing borders. 
*- Boints “NE by SW.” 


IDC_SIZENS ‘The double-headed arrow Windows uses when adjusting the top and bottom sizing borders. Points 
“North/South.” 


: IDC_SIZENWSE The double-headed arrow Windows uses when adjusting the upper right.and lower left sizing borders. 
- Points “NW by SE.” — 


IDC_SIZEWE The double-headed arrow Windows uses whe en adjusting the right or left sizing borders. Points “West/East.” 
IDC_UPARROW — Anarrow pointing up. . 
IDC_WAIT The hourglass cursor shape. 


Table 6-4. Predefined Cursor Names. 


Related ‘ees WM_ MOUSEMOVE, WM_SETCURSOR | 


. Example: In this example, a cursor was created using the SDKPaint program. The cursor is named in the 
resource .RC file as “hand.” The program creates a popup window when processing a 
_ WM_CREATE message. The popup window has its own window class, which specifies the “hand” 
icon. When the popup window is visible, the mouse shape will change to the “hand” icon anytime 
the mouse ee is within the popup window's client area. 


> Resource File ‘ 
/* generic.rce . 


#include <windows.h> 

#include “generic.h" 

popup ICON generic.ico 
hand CURSOR hand.cur 
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popup MENU 
BEGIN 
MENUITEM "&Do It!" IDM_DOIT 
MENUITEM “&Quit", IDM_QUIT 
END 


> WndProc() Function 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hDC ; /* device context handle */ 

Static WNDCLASS wndclass ; /* the window class */ 

static HWND hPopup, hParent ; 

switch (iMessage) /* process windows messages */ 


case WM_CREATE: /* build the child window when program starts */ 
wndclass.style 
~ = CS_HREDRAW | CS_VREDRAW | CS_PARENTDC ; 


wndclass.lpfnWndProc WndProc ; 
wndclass.cbClsExtra 0; 
wndclass.cbWndExtra 0; 
wndclass.hInstance ghInstance ; 
wndclass.hIcon NULL ; 


wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.lpszClassName 


LoadCursor (ghInstance, “hand") ; 
SELStOEROPIOGE CLTGRAY_BRUSH) ; 
NULL ; 

“SecondClass" ; 


Hun td vuu hou 


if(RegisterClass (&wndclass)) /* register the window class */ 
{ 


hPopup = CreateWindow ("SecondClass", "Popup Window", 
WS POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 50, 200, 150, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hPopup, SW_SHOW) ; 


pean 
[Other program lines] 
RELEASECAPTURE mWin2.0 mWin30 mWin3.1 
Purpose Releases capture of the mouse. 
Syntax void ReleaseCapture(void); 
Description The mouse is captured with the SetCapture() function. When a window captures the mouse, no 


other window receives mouse messages. ReleaseCapture() returns the mouse to the system, so 
that all windows can receive messages from the mouse. 
Uses SetCapture() is usually used with 
programs that outline or copy areas 
off the screen. . 


Returns No returned value (void). 

See Also SetCapture(), GetCapture() 

Parameters ——None (void). 

Related Messages WM_MOUSEMOVE Figure 6-4. ReleaseCapture() Example. 
Example This example, as illustrated in Fig- 


ure 6-4, displays the name of the window under the mouse cursor when the left mouse button is 
clicked. The mouse is captured when the user clicks the “Do It!” menu item. The mouse must be 
captured for this type of activity to avoid having control pass to the other window. The mouse 
remains captured until the right mouse button is clicked. 

oo FAR PASCAL WndProc CHWND hWnd, unsigned VEER rane WORD wParam, LONG lParam) 


HDC hoc ; 


181 


WINDOWS API BIBLE 


HWND hWndUnder ; 
POINT pMouse ; 
char cBuf £128], cWinName [64] ; 
switch Cimessage) /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
SetCapture (hWnd) ; /* capture mouse */ 
break ; 


case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; 
case WM_LBUTTONDOWN: /* show window under cursor */ 
pMouse = MAKEPOINT (lParam) ; “ 


ClientToScreen (hWnd, &pMouse) ; 
hWndUnder = WindowFromPoint (pMouse) ; 
GetWindowText ChWndUnder, cWinName, 63) ; 
hDC = GetDC ChWnd) ; 
SetBkMode (hDC, OPAQUE) ; 
TextOut (hDC, 0, 0, cbut, wsprintf (cBuf, 
“Window under cursor = 4S ap (LPSTR) cWinName)) ; 

Roreaseue ChWnd, hDC) ; 
break ; 

case WM_ RBUTTONDOWN: ae right mouse button reveases */ 
ReleaseCapture () ; : /* mouse */ 
break ; 

case WM_DESTROY: /* stop application */ 
“ReleaseCapture () ; 
PostQuitMessage (0) ; 
break ; : 

default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 

} * + . Fy 
return QL ; 


ScREENTOCLIENT 7 : ene S f mWin2.0 mWin3.0 mWin3.1 
Purpose .. Converts from screen coordinates to client window coordinates. . 
Syntax = void ScreenToClient(HWND hWnd, LPPOINT [pPoint); 
Description The.X and Y values in the lpPoint point structure are changed from screen coordinates (used by 
the mouse cursor) to client coordinates (used by painting functions). 
Uses “¢ Frequently used in conjunction with GetCursorPos() to convert the mouse cursor’s location to an 


X,Y location in the window’s client area. This is typically done when processing WM_MOUSE- 
MOVE messages while drawing lines or positioning text in the 


client area. =. ; g eneric, oe Ee 
‘Returns — No returned value (void). . Dolt! Quit 
See Also GetCursorPos(), ClientToScreen() | . = ze 
Parameters | —. [Client XY = 195, 58 
hWnd : HWND: A handle to the window which specifies the client area 
. _ to use in converting to client coordinates. . Figure 6-5. ScreenToClient() 
lpPoint | LPPOINT: A pointer to a POINT data structure. Initially holds Example. 


the screen coordinates. After ScreenToClient() is called, the 
POINT data contains the equivalent client coordinates. 


Related Messages WM _MOUSEMOVE, WM_ LBUTTONDOWN, WM_NCMOUSEMOVE 
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This example, as illustrated in Figure 6-5, shows the cursor’s location in both screen and client 
coordinates when the cursor passes over the nonclient area of the window. This includes the 
borders, caption, and menu bars. The WM_NCMOUSEMOVE message passes the screen coordi- 
nates of the cursor location as the Param value. This is converted to a POINT with the 
MAKEPOINT macro. ScreenToClient() converts the screen coordinates to client coordinates. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


HDC hDC ; 
POINT pMouSse ; 
char cBuf £128] ; 
switch (iMessage) /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_NCMOUSEMOVE: /* nonclient mouse movement */ 
pMouse = MAKEPOINT (lParam) ; 
hDC = GetDC ChWnd) ; 
SetBkMode (hDC, OPAQUE) ; 
TextOut ChDC, 0, 0, cBuf, wsprintf (cBuf, 
“Screen X,Y = %d, wd “, pMouse.x, pMouse. y)); 
ScreenToClient ChWnd, &pMouse) : : 
TextOut ChDC, 0, 20, cBuf, wsprintf (cBuf, 
"Client X,Y = %d, zd ‘', pMouse.x, pMouse.y)) ; 
ReleaseDC (hWnd, hDC) ; 
break ; ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; : 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} , 3 
return COL) ; 

} 

SETCAPTURE BWin2.0 mWin3.0 mWin3.1 

Purpose Captures the mouse so that only the program with the mouse canned receives mouse messages. 

Syntax HWND SetCapture(HWND hind); 

Description Normally, any active program running on the system can receive mouse messages. If a program 
calls SetCapture(), mouse messages are sent only to it. This makes it impossible to switch focus 
to another windaw until ReleaseCapture() is called. 

Uses Programs that grab screen images off of the screen. During the process of outlining an area to be 
copied, the mouse must be captured to avoid activating a window that the program is trying to 
copy. 

Returns Ahandle to the window that previously had the mouse captured. NULL ifno window had captured 
the mouse. 

See Also ReleaseCapture(), GetCapture() 
Parameters . 

hWnd HWND: A handle to the window that will capture the mouse. 
Related Messages WM_MOUSEMOVE, WM_SETFOCUS 
Example See the example under the ReleaseCapture() function description. 
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SerCanetBuinKTIME wWin2.0 mWin3.0 mWin3] 

Purpose Sets the rate at which the caret Fae flashes on the screen. 

Syntax _ void SetCaretBlinkTime (WORD wMSeconds); 

Description Sets the time, in milliseconds, between caret flashes. | 

Uses As the caret is a shared resource between all applications, changing the blink time in one appli- 
cation affects the blink time in all other programs running at that time. 

Returns No returned value (void). : 

See Also GetCaretBlinkTime() 

Parameters 

wMSeconds — WORD: The time in milliseconds between caret flashes. The default value is 500. This value can 
be changed from the Control Panel application. 

Example See the example under the GetCaretBlinkTime() function description. 

SETCARETPOS mw Win20 mWin3.0 mWin31 

Purpose Sets the position of the caret. 

Syntax void SetCaretPos(int.X, int Y); . 

Description The position is relative to the client region. The position of the cursor is changed even if the caret 
is hidden. | 

Uses This is the basic function for moving a caret shape on the window’s client area. A window can own 
a maximum of one caret at any one time. Use CreateCaret() to load or build a caret. 

Returns No returned value (void). 

See Also CreateCaret(), HideCaret(), ShowCaret(), DPtoLPQ) 

Parameters | = 

x _ int: The horizontal position in logical units in the window's client area. 

Y int: The vertical position in logical units in the window’s client area. 

In the default mapping mode, the origin is the upper left corner and the X,Y locations are 

measured in pixels. Use SetMapMode() to change the coordinate system of the client area (see 
Chapter 10, Device Contexts). . 

Example When the user clicks the left mouse button, the caret is relocated to that position in the client 


area of the window. The mouse location has to be converted from screen coordinates to the client 
location used by SetCaretPos() using the ScreenToClient() function. This example is simplified 
by using the MM_TEXT mapping mode. In this mode, the logical units equal the client area pix- 
els, measured from the upper left corner of the client area. See Chapter 10, Device Contexts, for 
a discussion of mapping modes and logical coordinates. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ ; : 


' POINT. 


‘Switch (CiMessage) 


pCursPoint ; 
/* process windows messages */ 


case WM_CREATE: 
CreateCaret ChwWnd, Ruths 3, 20) ; 
SetCaretPos (10, 10) ; 
- ShowCaret (hWnd) ; 
break ; 
case WM _ COMMAND: /* process menu itens */ 
switch (wParam) 
{ 


‘case IDM_QUIT: /* send end of application message */ 
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DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_LBUTTONDOWN: 
GetCursorPos (&pCursPoint) ; /* get cursor x,y */ 
ScreenToClient (hWnd, &pCursPoint) ; /* to client coord */ 
SetCaretPos (pCursPoint.x, pCursPoint.y?) ; 
break ; 
case WA_DESTROY: /* stop application */ 
PostaquitMessage (0) ; 
break ; 


default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 


} 
return (OL) ; 


} 


_ SeTCursor 
Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
hCursor 


M@Win2.0 m8Win3.0 wWin3d] 
Establishes which cursor shape to display. 
HCURSOR SetCursor(HCURSOR hCursor); 


Cursor shapes must first be loaded with LoadCursor(). SetCursor() is normally used to change 
the shape of the cursor when processing WM_SETCURSOR or WM_MOUSEMOVE messages. This 
function is fast if the cursor has already been used once, so it can be called repeatedly to change 
a cursor shape without noticeably slowing the program. 


Used to change the cursor shape in windows that do not have a cursor loaded as part of the 
window class definition. If you attempt to use this function within the bounds of a window that 
has a cursor defined in its class definition, the cursor shape will flicker. This is because Windows 
is switching back and forth between the class cursor and the cursor loaded with SetCursor() . 
every time a WM_MOUSEMOVE message is sent. Set the class cursor to NULL to avoid this prob- © 


- lem. 


A handle to the previous cursor shape. 


~ LoadCursor() 


HCURSOR: A handle to the cursor to show. Use LoadCursor() to obtain this handle. You can 
combine these functions into a single line: 


SetCursor (LoadCursor (NULL, IDC_WAIT)) ; 
Related Messages WM_SETCURSOR, WM_MOUSEMOVE 


Example 


This example shows a program that switches between two different cursor shapes. The window's 
class definition in WinMain() does not load a cursor shape (NULL value). Two different cursors 


are loaded when the program processes a WM_CREATE message. One is the predefined Windows __ 


arrow, and the second is a custom cursor called “hand,” which is referenced in the resource RC 
file. When the user clicks the “Do It!” menu item, the program switches to showing the hand 
cursor shape. 


C> The Resource File 


/* generic.rc 


Sey 


Hinclude <windows.h> 
Hinclude “generic. h" 


generic ICON: 
hand 


generic MENU 
BEGIN 


generic.ico 
CURSOR hand.cur 
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MENUITEM "&Do It!" IDM_DOIT 
MENUITEM "&Quit", IDM_QUIT 
END 
One line of the WinMain() function is shown here because it is a little unusual. It has no 
defined-cursor shape in the class definition. 


oS WinMain() Rinehen Excerpt 


wndclass.hCursor YY : = NULL ; 


" WINCREATE message triggers loading of the ¢ cursor cen The “word ” cursor is loaded 
from the resource data. 


> The WndProc() Function 


Long FAR PASCAL WndProc CHWND hWnd, ceeds iMessage, WORD wearain: LONG lParam) 
{ 


static HCURSOR hHandCursor, hArrowCursor ; 

static BOOL bUseHand = FALSE ; 

switch (iMessage). are /* process windows messages */ 
{ ‘ : . 


case WM_CREATE: : a ; 
hArrowCursor = LoadCursor (NULL, IDC_ARROW) ; 
SURARA CUT SOn = LoadCursor (ghInstance, (LPSTR) “hand") ; 
break ; 1% , . 
case WM_ SETCURSOR: 
if (bUseHand) 
SetCursor (hHandCursor) ; 


else 
SetCursor ChArrowCursor) ; 
_ break ; ee 1 * 
‘case WM_COMMAND: fe /* process menu items */ 
switch CwParam) " - 
{ eS. & 
-case IDM_DOIT: /* User hit the "Do it" menu item */ 
: bUSeHand = TRUE ;/* switch to’a hand shaped cursor */ 
break ; 
case IDM_QUIT: /* send end of APP ETCAtAoN message */ 
PostQuitMessage | CNULL) 33° 
break ; 
} 
break ; 
case WM_ DESTROY: /* stop application */ 
‘Postaui tMessage (0). ; : ; 
break ; eee ‘ “ Edin 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} - 
return (OL) ; my _— eos te 
} 
SeTCursorPos | fi Win 2.0 Win3.0 em Win3.1 
Purpose —«-_—— Moves the mouse cursor te a new location. _ 
Syntax a void SetCursorPos(int X, int Y); . gist ; 
Description The location is given in screen coordinates. Use ClientToScreen() to convert from client window 
coordinates to screen coordinates. 
Uses Not often used. SetCursorPos() could be used to provide keyboard support for mouse movements. 
. For example, the arrow keys might move the mouse cursor. 
Returns — No returned value (void). i 
See Also GetCursorPos(), ClientToScreen() 
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Parameters 
Xx 


Y 


Related Messages 


Example 


int: The horizontal location for the mouse cursor, in screen coordinates. Zero is the left side of 
the screen. 


int: The vertical location for.the mouse cursor, in screen coordinates. Zero is the top of the 
screen. 


WM_MOUSEMOVE 


When the user clicks the “Do It!” menu item, the mouse cursor is moved to the upper left corner 
of the window’s client area. This location is computed by loading 0,0 into a point structure, and 
then using ClientToScreen() to convert to screen coordinates. SetCursorPos() uses the screen 
coordinates to relocate the mouse cursor. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


POINT 


{ 


} 


} 


pCursPoint i 


switch (CiMessage) - ' /* process windows messages */ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) ; 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
pCursPoint.x = 0 r/* specify 0,0 - top left corner */ 
pCursPoint.y = 0; 
ClientToScreen Grands &pCursPoint) ; /*®* screen coord. */ 
SetCursorPos (pCursPoint. x, pCursPoint.y) ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; ; 
case WM_DESTROY: /* stop application */ 
post luretessage (0); . 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


SETDOUBLECLICK TIME mWin2.0 m8Win3.0 wWin3l 


Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Changes the mouse button double-click time. - 

void SetDoubleClickTime(WORD wCount); 

The double-click time is the number of milliseconds between two mouse clicks. Clicking faster 
than this value generates a WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, or WM_RBUT- 
TONDBLCLK message for the left, middle, or right mouse buttons, respectively. Note that the 
WM_LBUTTONDOWN, etc. messages will always be received prior to getting the double-click 
message. 

Used to change the current double-click time value. The double-click time is only changed for the 
duration of the Windows session. To permanently change the double-click time setting in 
WIN.INI, use the Control Pannel application or WriteProfileString(} (see Chapter 20, MS-DOS 
and Disk Fill Access). 

No returned value (void). 7 i 


SetDoubleClickTime(). 
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Parameters _ 
wCount 


Related Messages 
Example 


SHOWCARET 
Purpose 

Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
hWnd 


Example 


SHOWCURSOR | 


Purpose 
Syntax | 
Description 


_ Uses . 
. Returns 


Parameters 
bShow 
_ Example 


WORD: The new-double click time in milliseconds. 
WM_LBUTTONDBLCLK, WM_MBUTTONDBLCLK, WM_RBUTTONDBLCLK 
See the example under the GetDoubleClickTime() function description. 


e@Win2.0 m@Win30 msWin3.1 
Makes the caret visible at its current location. 


void ShowCaret(HWND hWnd); 


The caret must be created with CreateCaret() before it can be visible. As soon as ShowCaret() is 
called, the caret immediately starts blinking. The caret remains visible until HideCaret() or 
DestroyCaret() is called. If HideCaret() has been called more than once, an equal number of 
ShowCaret() calls will be needed before the caret becomes visible. 

It is frequently desirable to hide the caret while processing WM_PAINT messages, or while the 
user is doing operations that take the focus of activities away from the client area (menu selec- 
tions, etc.). When the user returns to the work area, the caret can be made visible again with 
ShowCaret(). The caret is shared by all applications. If a caret is displayed on one program's 
window, a caret in another running program’s window will disappear. 

No returned value (void). 


HideCaret(), DestroyCaret(), SetCaretBlinkTime() 


_ HWND: A handle for the window that owns the caret. A window can only own one caret at one 


time. Use CreateCaret() to add a caret shape to a window. 
See the example under the CreateCaret() function description. | 


wWin2.0 mWin3.0 mWin3.1 
Shows or hides thé cursor. , 
int ShowCursor(BOOL bShow); 


If bShow is FALSE (zero), ShowCursor() hides the cursor. If bShow is TRUE, the cursor is dis- 
played. Multiple calls to ShowCursor() to hide the cursor require an equal number of calls with 


‘bShow TRUE to restore it. 


Used to show the cursor on systems that tig not have a mouse. 


int, the new display count. Each call with bShow TRUE increases the count. Each call with bShow 
FALSE decreases it. The cursor is shown as long as the display count is zero or greater. On sys- 
tems without a mouse, the display count is initially set to—L. 


BOOL: ‘TRUE to show the cursor, FALSE to hide it. 


‘This example shows a crude emulation of the mouse for a program running on a machine that 


does not have a mouse. The cursor shape is displayed in the upper left corner of the client area 
when the program begins. Pressing the arrow keys moves the cursor. Activating the “Do It!” menu 
item (with Gin) (att)-D) hides the cursor. 


none FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG tParam) 
{ 


static 


POINT  pCursor ; 


switch (iMessage) . /* process windows messages */ 
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case WM_CREATE: 
pCursor.x = 10 
pCursor.y = 10 
‘ChLientToScreen (hWnd, &pCursor) ; 
ShowCursor (TRUE) ; 
SetCursorPos (pCursor.x, pCursor.y) ; 


/* start with cursor in client area */ 


. 
f 

. 
’ 


break ; ; ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* erase the cursor shape */ 
ShowCursor (FALSE) ; . 
break ; 


case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; 
case WM_KEYDOWN: 
switch (wParam) } /* simple mouse emulation */ 
' case VK_LEFT: /* Left cursor key */ 
pCursor.x -= 10 ; 
break ; 
case VK_RIGHT: /* right cursor key */- 
pCursor.x += 10 ; 
break ; 
N case VK_UP: /* up cursor key */ 
eCursor.y -= 10 ; 
break ; 
case VK_DOWN: /* down cursor key */ 
pCursor.y += 10 ; 
break 
} 
SetCursorPos (pCursor.x, pCursor.y) ; 
break ; 
case WM_DESTROY: '/*® stop application */ 
PostQuitMessage (0) ; 
. break 
default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
} 
return (OL) ; 


SwapMovusEBuTToNn @Win2.0 mWin30 mWin3.! 
Purpose Reverses the right and left mouse buttons. 
Syntax BOOL SwapMouseButton(BOOL bSwap); 
Description If bSwap is TRUE, the right mouse button generates left mouse button messages (WM_LBUTTONDOWN), 


and the left button generates right mouse button messages (WM_ ieuhna. IfbSwap is FALSE, the 
normal mouse messages are sent. 


Uses Handy for adapting the mouse to left-handed users. Calling this function only changes the mouse 
button orientation for the duration of the Windows session. Use the Control Pannel application to 
make a permanent change in the WIN.INI file, or call WriteProfileString() (see Chapter 20, MS- 


DOS and File Access). 
‘ Returns BOOL. TRUE if the mouse buttons are reversed, FALSE if they are “ioral 
Parameters 
bSwap _, BOOL: TRUE if the mouse buttons are to be reversed, FALSE if they are to be normal. 


Related Messages WM_LBUTTONDOWN, WM_RBUTTONDOWN 
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Example 


{ 


A message is printed on the client area when a WM_LBUTTONDOWN message is received. The 
message is erased when a WM_MOUSEMOVE message appears. Clicking the “Do It!” menu item 
_swaps the two mouse buttons, so the right button ends up generating the WM_LBUTTONDOWN 
messages. Clicking the “Do It!” menu item a second time (using the right mouse button) restores 
the mouse to normal operation. == . ; 


Long FAR PASCAL WndProc CHWND hWnd, unsigned -iMessage, WORD wParam, LONG lParam) 


{ 


HDC hDC ; 
static BOOL bMouseSwap = FALSE ; 
switch (CiMessage) , /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
af 


case IDM_DOIT: 
if (bMouseSwap) 


{ 
bMouseSwap = FALSE ;. 
SwapMouseButton (FALSE) ; 
} 
else 
{ 
bMouseSwap = TRUE ; 
SwapMouseButton (TRUE) ; y 
} 
break ; 
_case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; | 
break ; 
} 
break ; ; : 
case WM_MOUSEMOVE: /* writes over old messages as mouse moves */ 


hDC = GetDC (hWnd) ; 
SetBkMode (hDC, OPAQUE) ; 


TextOut (hDC, 10, 30,.." ", 30) ; 
ReleaseDC (hWnd, hDC) ; ae 
. break ; 
case WM_LBUTTONDOWN: - /* Left mouse button down */ 


hDC = GetDC ChWnd) ; 
TextOut ChDC, 10, 30, "Got a left button!", 17) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case WM_DESTROY: /* stop application */ 
SwapMouseButton (TRUE) ; 
PostQuitMessage (0) ; 
break ; : 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return. (OL) ; 
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All Windows programs use the keyboard to some extent. In general you will find that much of the support for keyboard 
input is built into predefined tools such as edit controls and menu accelerators. These tools free the programmer from 
having to deal directly with the keyboard in many cases. Some programs, such as word processors, make heavy use of 
the keyboard for input. Windows provides extensive support for the keyboard to satisfy these demands. 


Virtual Keys 


PC keyboards have evolved to include more keys ard several “standard” layouts. Realizing that no end to keyboard 
changes was in sight, the designers of Windows came up with the concept of a “virtual key.” The idea is that no matter 
what make or model of keyboard the user has, the virtual key code for the first function key would always be the same. 
This frees the programmer from having to consider what type of keyboard is installed. 

The definitions of all the virtual key codes are given in the WINDOWS.H header file. Table 7-1 gives all of the sous 
and their meanings. The vitural code for the character and number keys is the same as their ASCII equivalents (in 
uppercase) and are not included in the table. Chapter 19, Character Sets and Strings, includes a table of the ASCII 
and ANSI character sets, which both have the same codes for unaccented letters and numbers. Note that the numeric 
keypad numbers are given different codes from the numbers on the top row of the conventional keyboard. Also note 
that there is only one virtual key code for the shift keys. Both shift keys generate the same VK_SHIFT. 

Be cautious in assuming that a given virtual key will be available on any keyboard. For example, many keyboards 
only have ten function keys, even though Windows makes provision for 16. Also note that the ASCII value for the “*”, 
“7, “-”, and “+” keys generally are sent from the numeric keypad, not VK_MULTIPLY, etc. which are specific to certain 
OEM keyboards. 


Virtual Key Code Value (hex) Meaning - - : Xx] 
VK_ACCEPT Ox1E Kanji only (Japanese characters) 

VK_ADD 0x68 Pluskey 

VK_BACK 0x08 Backspace 

VK_CANCEL 0x03 Contro!-break 

VK_CAPITAL 0x14 "Shift lock 

VK_CLEAR Ox0C Clear key (Numeric keypad 5) ~ 
VK_CONTROL Ox11 = ——s Control Grad) key | 
VK_CONVERT _ Ox1C Kanji only (Japanese characters) 

VK_DECIMAL Ox6E Decimal point 

VK_DELETE Ox2E . Delete 

VK_DIVIDE Ox6F Divide (/) key 

VK_DOWN 0x28 Down arrow 

VK_END 0x23 End 
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VK F16 
VK_HIRAGANA 
VK_HOME 
VK_INSERT 
VK_KANA 
VK_KANUI 
VK_LBUTTON 
VK_LEFT 
VK_MBUTTON 
VK_MENU 
VK_MODECHANGE 
VK MULTIPLY 
VK_NEXT 
VK_NONCONVERT 
VK_NUMLOCK 
VK_NUMPADO 
~VK_NUMPAD1 
VK_NUMPAD2 - 
VK_NUMPAD3 
VK_NUMPAD4 


0x1B 
* 0x2B 


0x70 
0x71 
0x72 
0x73 


0x74 


0x75 
0x76 
0x77 
0x78 


0x79» 


Ox7A 
0x7B 
Ox7C 
Ox7D 
Ox7E 
Ox7F 
0x18 
0x24 
Ox2D 


0x15. 


0x19 
0x01 


0x25 


0x04 
0x12 
Ox1F 
Ox6A 
0x22 
0x1D 
0x90 


0x60 - 


0x61 
Ox62 


0x63 
0x64 


Escape (Esc) 
Execute key (if any) 
Function keys 


| Enhanced keyboard only 


Enhanced keyboard only . 
Specialized keyboards only 
Specialized keyboards only 
Specialized keyboards onty 
Specialized keyboards only 
Kanji only (Japanese characters) 
Home 

Insert 

Kanji only (Japanese characters) 


’ Kanji only (Japanese characters) 


Left mouse button 

Left arrow 

Middle mouse button 

Menu key (if any) 

Kanji only (Japanese characters) 
Multiply key 

Next 

Kanji only (Japanese characters) 
Num Lock 

Numeric keypad keys 
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VK_NUMPAD5 Ox65 


VK_NUMPAD6 Ox66 

VK.NUMPAD7 ; Ox67 ° 

VK_NUMPAD8 0x68 

VK_NUMPAD9 Ox69 

VK_PAUSE 0x13 Pause 

VK_PRINT . Ox2A . Print Screen (Windows versions below 3.0) 
VK_PRIOR 0x21 | Page up 

VK_RBUTTON 0x02 Right mouse button 

VK_RETURN Ox0D Return 

VK_RIGHT , 0x27 Right arrow 

VK_ROMAJI 0x16 Kanji only (Japanese characters) 

VK_SELECT 0x29 Select key (if any) 

VK_SEPARATOR Ox6C Separator key (if any) 

VK_SHIFT 0x10 Shift 
VK_SNAPSHOT Ox2C Print Screen (Windows 3.0 and later) | 
VK_SPACE 0x20 . Spacebar ; = 
VK_SUBTRACT Ox6D ‘Subtraction key 

VK_TAB 0x09 Tab key 

VK_UP 0x26 Up arrow 
VK_ZENKAKU 0x17 Kanji only (Japanese characters) . 


*(The vitural key codes for the letters A to Z and the digits 0 to 9 are their ASCII values) 


Table 7-1, Virtual Key Codes. * ’ _ — 


| Keyboard Messages eS z 


Windows lets your program know about keypresses by sending messages. The most common series of messages is the 
following: 


WM_KEYDOWN _ Notification that a key has been disnresiedl: 
WM_CHAR The ASCII code for the letter—if a character (not a function key, cursor arrow, etc.) was pressed. 
WM_KEYUP ___ Notification that'a key has been released. 


The WM_CHAR message is generated by the TranslateMessage() function in the message loop of the application’ Ss. 


WinMain() function. This function is discussed in Chapter 9, Windows Messages.Generally you will use the 
WM_KEYDOWN message to look for function keys, cursor keys, the numeric keypad, and the edit keys such as (Pour), — 
(PcbN), etc. These are the keys which make the best use of Windows’ virtual key code system. WM_CHAR is used to 
retrieve ASCII keyboard inputs such as letters, numbers, and printable symbols. Using the WM_CHAR message is 
Simpler for letters, as the upper and lowercase letters have different ASCH values. With WM_KEYDOWN, you have to 
check whether the key is depressed and check the virtual key code for the letter, which is always the capital 
letter’s ASCII value. If the user depresses the key while pressing another key, Windows sends system key mes- 
sages. The sequence is WM_SYSKEYDOWN, WM_SYSCHAR, and WM_SYSKEYUP. It is unusual to process these mes- 
sages directly, as they are normally used for keyboard accelerators. Accelerators are explained in:the Keyboard 
Accelerators section. Like all Windows messages, the keyboard messages pass information to your program’s 
WinProc() function(s) in the wParam and lParam paielete The information you will use most often is inwParam. 
(See Table 7-2. } 
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WM_KEYDOWN = ~—Ss The virtual key code for the key pressed. ~ 
WN_CHAR The ASCII code for the character represented by th the iy 
-WN_KEYUP The virtual key code for the key pressed. 
WN. SYSKEYDOWN ~. The virtual key code for the key pressed (Air) Key depressed at the.same time). 
WM_SYSCHAR . | The ASCII code for the character represented by the key (GAT) (D key depressed at the same 
- time). 
- WMLSYSKEYUP The virtual key code for the key pressed (AED) key depressed at the same time). 


Table 7-2. wParam Meaning in Keyboard Messages. 


~- There is a lot of other information encoded in the /Param parameter, such as the hardware (OEM) code for the 
key pressed, how many times the key was pressed, etc. This information is fully explained in Chapter 9, Windows 
Messages. For the most part, you will not need this information, and can use the wParam data directly in your pro- 
. gram. Listing 7-1 shows an example of how these messages are processed. In this case, a single line of text is created 
on the program’s client area. Typing adds to this line, hitting the backspace key removes text from the end. This is an 
extremely simplified example, but it does provide an outline for how text messages are processed. 


© Listing 7-1. Keyboard Input Message Processing* ' 
#define BUFSIZE 256 


tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG (Param) — ia 
{t ¢ 


HDC hoc ; 
static char cCharBuf CBUFSIZE]J ; ; eM : 
Static int. nCharFos =O; | : 
switch (iMessage) /* process windows messages */ 
case WM_CREATE: : - 
cCharBuf COI] =O; . /* start with null string */ 
break ; 
case WM_CHAR: /* add and display char input from keyboard a 
if (wParam pz ' ' & nehartos < BUFSIZE) 
€ 


cCharBuf CncharPost+) » = wParam 7 3 /* add new Latter a] 
cCharBuf CnCharPos] = /* new ‘termynal null */ 
} 
InvalidateRect (hWnd, NULL, TRUE) ;/* show-updated Line a] 
' UpdateWindow (hWnd) ; ; 
hDC = GetDC ChWnd) ; 
TextOut (hdc, 0,.0, “echarBut, strlen (cCharBuf)) ; 
ReleaseDC hwnd, hDC) ; 
‘break ; 


case WM_| KEYDOWN: : 
switch (wParam) /* rudimentary editing commands */ 
{ ; : . 
case VK_BACK: , /*® backspace */— 
if (nCharPos > 0) ; ss 
{ 
nCharPos ~-; 
cCharBut [ncharPos] =0; 
5 : } 
; [ : : break ; 
: cr case VK_ RIGHT: /* right arrow. key af 
/* other edit procedures / 
, break. ; 
rp }! : a ; 
‘ lanvatidateRect Chiind, NULL, TRUE) ; /* ‘chew updated Line */— 


| UpdateWindow Chwnd) ; ‘ 
ADC = GetDC (hWnd) ; : ete «4 
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TextOut ChDC, 0, 0, eCharbut, strlen (cCharBuf)) ; 
ReleaseDC Chunds hOCc) ; 
break ; 
case WM_ COMMAND: /* process menu items */ 
, switch (wParam) . 
or —— { 
case IDM_DOIT: , 
HessageBox ChWnd, "Type something!", "Message", MB_OK) >; 


break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_ DESTROY: : /* stop application oy 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 


return DefWindowProc ChWnd, iMessage, wParam, LParam) ; 
} 
return (OL) ; 
} 
*Only the WndProc() aaneHons is shown. The remainder of the program is identical to the GENERIC application in 
Chapter 1. 


‘ Messages with Non-English Keyboards 


English uses a simple alphabet of 26 characters in two cases (upper- and lowercase). Many other languages also have 
accent characters and other symbols. When you install Windows, you select the assumed language. This loads a file 
which ends up named OEMANSL.BIN in the Windows directory. You can find out which language file is loaded by — 
calling the GetKBCodePage() function. The OEMANSI.BIN file contains all of the data Windows needs to adjust me 
keyboard map for the different language’s symbols and key layout. 

To generate accented characters, users of non-English keyboards use key combinations that tell Windows that the 
next key combination is to be accented. For example, a French accent circumflex (“) over a character is set by @rat)-[ 
and then the letter key. This only works if you have the French OEMANSI.BIN file loaded as part of Windows’ install. 
You can track these extra keystrokes through the WM_DEADCHAR message. For the creation of an accented eet 
your WinProc() function would see the following sequence of messages: 


WM_KEYDOWN - Pressing the accent key. 
- WM_DEADCHAR The character message for the accent. 


WM_KEYUP : “Releasing the accent key. 

WM_KEYDOWN Pressing the letter key (that will end up accented). 
WM_CHAR The character code for the accented letter. 
WM_KEYUP Releasing the letter key. 


Normally you will not need to track all of this, as the accented character has a different ohoaattes code than the 
unaccented version. Tables of the character values are given in Chapter 19, Character Sets and Strings. 


Keyboard Accelerators 


Another built-i in convenience provided by Windows is a direct way to provide keyboard shortcuts for menu éoniiuaniis . 
and other commands. These are called “accelerators.” You do not have to use accelerators in your program. The same 
effect can be achieved by interpreting keyboard input messages. The main reasOn to use accelerators is that they are 
so simple. A few minutes of work will provide a complete set of keyboard alternatives to your mouse driven menu . 
- commands. This isin addition to the normal key alternatives for menu items with names that are proceeded by “&” 
characters, See Chapter 4 on menus if this is not familiar. . 

An important difference when using keyboard accelerators is that Windows will translate the keystroke message 
into the equivalent menu command. In other words, pressing an (4t1)-key combination will generate a WM_COMMAND 
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‘message, not the WM_KEYDOWN sequence that follows a normal keypress. Your application can process the menu 

item WM _ COMMAND message as if the menu item were selected with a mouse click. The user will even see the menu 
item flash for selection as the accelerator keypress is acted on. The keyboard accelerators are defined in your 
program’s resource .RC file. Listing t- 2 is an example of a complete .RC file, with both amenu and keyboard accelera- 
tors defined. 


> Listing 7-2. A Resource File with uReyioerd ‘Accelerators 


/* generic.rc */ 


. #incelude <windows.h> 
#include “generic.h" 


generic ICON generic.ico . 
generic : MENU 
BEGIN : _ ; : iy 
POPUP "&First Menu" 
BEGIN 
MENUITEM “&Display Items (Ctrl-D)", — IDM_TOP1 
MENUITEM "&1st Option (F1)", ‘IDM_OPT1 
MENUITEM SEPARATOR ; : am: 
MENUITEM "&2nd Option (F2)", IDM_OPT2. 
END ” Sys 
MENUITEM “&Quit (End key)", IDM_QUIT 
END 
generic ACCELERATORS 
BEGIN 
“p", _ IDM_TOP1, VIRTKEY, CONTROL 
VK_F1, IDM_OPT1, VIRTKEY 
VK_Fe, IDM_OPT2, VIRTKEY, NOINVERT - 
- VK_END, IDM_QUIT, " WIRTKEY ? — 
VK_F1, | : NOTMENU, VIRTKEY, ALT ; 
’ END : 


The accelerator table is structured like a menu definition, although there is no equivalent to a popup menu. The 
table is given a name, in this case “generic.” This is the name which your program will use to get the accelerator table 
ready for use with LoadAccelerators(). You can have more than one table of accelerators in the .RC file, each with a 
different name. The lines for each keyboard accelerator are between the BEGIN and END lines of the ACCELERATOR 
definition. The format is 


tablename | ACCELERATORS 

BEGIN 

event, idvalue, -LASCII or VIRTKEY], CALTI, CCONTROLI, CNOINVERTI, CSHIFTI 
END 


ASCII and VIRTKEY are “event types.” The events can be any of the ones listed in Table 7-3. 
EventType === =—~-—- Meaning 


“char” (No Event Type) . A single ASCII character enclosed in double quotes. The character can also be preceded by a 
: ~“A® to signify a control character. 
_ ASCII . . _ Aninteger value for an ASCII character. In this case, specify ASCII after the idvalye 
Virtual ey The uppercase letter.or single digit enclosed in double quotes (eg., “A” or “1”). For non-ASCII | 


use the VK_ code for the key. Specify VIRTKEY after the idvalue. 
. Table 7-3. Keyboard ‘Accelerator Event Types. 


_ The idvalue can be any integer. The idvalues are normally defined in the program’s header file and, in most 
cases, Will-be the same as the corresponding menu item ID value. This integer idvalue will be the wParam parameter 
when the program receives a WM_COMMAND message from Windows after the user presses the accelerator. The ID 
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values do not have to correspond to menu items. For example, you might have an accelerator key for scrolling the 
window’s client area. The scroll bar control is not part of the menu, so no equivalent menu ID value will exist. Create 
separate ID values in the header file for these items, and then put the corresponding logic in your WM_COMMAND 
message processing code to handle the scrolling. The last parameters in the definition of accelerator keys are the 
options. They can be any of the values shown in Table 7-4. The ALT, CONTROL, and SHIFT options apply only to virtual 


key (VIRTKEY) accelerators. | 
“Accelerator Option. = Meaning 


ALT The keyboard accelerator is activated only if the key is depressed. 
. CONTROL The keyboard accelerator is activated only if the key is depressed. This has the same 
‘effect as putting a “A” in front of the accelerator character, but is more readable. 
NOINVERT The corresponding menu item is not flashed when the accelerator | is activated. Normally, the top 
menu line flashes. 
SHIFT The keyboard accelerator is activated only if either of the keys is depressed. 


Table 7-4. Accelerator Options. 
The only other changes necessary to include accelerators are two added lines in the Wefan) function. Without 
accelerators, the window’s message loop looks like: 
while (GetMessage (&msg, NULL, 0, 0)) /* the message Loop */ 
{ 


TranslateMessage (msg) ; 
DispatchMessage (&msg) ; 
‘} 
, This functions simply to pull messages in from the message queue and send them on to the program’s message 
processing function (like WinProc()) to be handled. To have chad accelerators interpreted, change the message 


- loop to look like 
hAccel = LoadAccelerators (hInstance, gszAppName) ; 
while (GetMessage (&msg, NULL, 0, 0)) —/* the message Loop */ 
{ " 


if (!TranslateAccelerator ChWnd, hAccel, &msg)) 
{ 


TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} : . x 
LoadAccelerators() reads the accelerator table in from the resource data and provides a handle to the table. The 
TranslateAccelerator() function checks incoming keystrokes for a match in the accelerator table. If a match is found, 
a WM_COMMAND message is sent directly to the program’s message function. The wParam parameter passed with 
WM_COMMAND is set equal to the accelerator ID value. If no match is found, the character messages for the keypress 
are sent. Notice that the modified message loop with TranslateAcceleratorQ) is set up so that messages that do not 
match an entry in the accelerator table still get passed to the regular TrarslateMessage() and DispatchMessage() 
functions. If a match is found, TranslateAccelerator() returns a nonzero value, so the normal message functions are 
bypassed. This stops your program from getting both the accelerator message and the untranslated keyboard mes- 
sages. 
Note: You can create accelerators for the system menu commands (the commands that alow up when you click 
the button in the upper right corner of the program’s main window). In this case, the SC_RESTORE, SC_MOVE, 
SC_SIZE, SC_MINIMUM, SC_MAXIMUM, or SC_CLOSE values will be used for the ID values, and the mesnee Ds: 
cessing function will receive a WM_SYSKEYDOWN message instead of WM_KEYDOWN. 
_ Caution: Accelerator keys are’ easy to program, but not necessarily easy for the user to einarabee: A ica prac- 
tice is to include the accelerator equivalent to each menu item to the right of the menu name for each menu item that 
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has an accelerator. Including the description in the program ’s help file is a good idea too! There are a few “standard” 
keyboard accelerators. defined i in the CUA Advanced Interface Design Guide. Use the assignments in Table 7-5 if at all 
possible. 


° @O oe Undo previous action. 


a “=. Clear sélection (not saving the selection to the clipboard), 
° GTRL)-(INS) + Copy (put selection into clipboard). 
(SHiET)-(NS) Paste (insert clipboard contents at the current active location). 
GHIFT)-(DEt) Cut (put selection into clipboard, and clear it from the screen). 
GD - Help. See Chapter 27 for how to construct context-sensitive ehept files. 
®) - : File. Activates a file dialog box is most cases. 
. Next window. . 
(SHIFT)-(F6) . Previous window. 


‘Table 7-5. Recommended Keyboard Accelerators. 


Keyboard Function Summary 
Table 7-6 summarizes the keyboard functions. The detailed function descriptions follow the table. 


EnableHardwarelnput Enable or disable the mouse and keyboard. 


GetAsyncKeyState Find out if a key has bedn pressed. 
GetInputState Determine if there are mouse button, keyboard, or timer events in the message queue. 
_ GetKBCodePage Find out which OEM/ANSI keyboard driver table is loaded. | 
GetKeyboardState - Find out the status of all of the keys in one function call. 
GetKeyboardType Retrieve the type of keyboard or-the number of function keys. 
a GetKeyNameText Retrieve the name of a key. 
__. GetKeyState Determine if a key is currently down, or if a toggle key is active. 
LoadAccelerators Load the accelerator key combinations from the resource file. 
MapVirtualkey . _ Convert between virtual key codes, ASCII, and scan codes. 
OemKeyScan Convert from ASCII, to the keyboard's OEM scan code. 
SetKeyboardState , Set the keyboard status for all 256 virtual keys in one function call. 
; TranslateAccelerator Translate keystrokes into commands using the accelerator table. 
-VkKeyScan Translate an ANSI character to the corresponding virtual key code. 


Table 7-6. Keyboard Function Summary. 


Keyboard Function Descriptions 


ENABLEHARDWAREINPUT = =~ : BWin2.0 mWind0 mWin3l 
Purpose Enables or disables the mouse and eyhoard. 


Syntax - Bee Baablefiardwarcinpat(B00L ates, 
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Description _ This function allows you to completely disable all input from the mouse and keyboard. The mouse 
cursor is frozen on the screen, and the only key combination that has any effect i Js the (irr) CiaL)-GiD- 
(Get) combination for a warm boot of the computer. 


Uses Use with great care. EnableHardwareInput() may be useful in time-critical applications such as 
real-time data acquisition. Be sure to set a system timer (see the example) so that the system will 
restore itself at intervals. Otherwise, the only way to revive the computer is with a warm or cold 


boot. = - fs 
Returns — BOOL. TRUE if the system is enabled, FALSE if ssn 
See Also EnableWindow()’ 
Parameters / 


 pEnableinput —_- BOOL: Set to TRUE to enable the system, FALSE to disable it. 
Related Messages WM_TIMER / 


Example When the user hits the “Do It!” menu item, the mouse and keyboard are disabled for " seconds. 
A timer revives the system when a WM! TIMER message is received. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : 
HDC hoc ; 
switch (iMessage) : /* process windows messages «/ 


case WM_TIMER: /* Restore mouse and keyboard operation */ 
EnableHardwarelInput STRUED . 
KilltTimer (hWnd, 1) ; 
hDC = GetDC ChWnd) ; 
TextOut (hDC, 10, 10, “Should be shablva now.", 22) ¢ 
ReleaseDC ChWnd, hDC) ; 
break ; 

case WM_COMMAND: /* process menu items */ 
switch (wParam) ; 


case IDM_DOIT: 
if C!SetTimer (hWnd, 1, 10000, NULL)? | 


¢ 
MessageBox (hWnd, 
“Too many clocks or timers!", , Warning", 
MB_. TCONEXCLAMATION | MB_OK) ; 
} 
else /* Disable mouse ae keyboard for 10 sec */ 
{ 
EnableHardwareInput (FALSE) ; 
hOC = GetDC Chiind) ; 
TextOut ChdCc, 10, 10, 
J “Disabled for 10 Paeling an 3 
-ReleaseDC (hWnd, hDC) ; 
} 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; , 
break ; 
. : } 
break ; 
case WM_DESTROY: [* stop Spplication */ 
PostQuitMessage (0) ; 
break ; nS 
default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
> | ‘ 
return COL) ; 
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GerAsyncKeySrate ek. Wine) ws Wink.0)| mw Win3.l 


Purpose. 
Syntax 
Description 


Uses 
. Retarns 


See Also 
Parameters — 
vKey Wyk 
Related Messages 
Example 

rede FAR PASCAL 


HDC 
int 


switch 
{ 


+ 
return 


Finds out if a key is depressed. 


. int GetAsyncKeyState(int vXey); 


This function will determine if a key is currently pressed, or if it has been ne after the last 


- call to GetAsyncKeyStateQ). 


Particularly useful for applications that use shifted keys or function keys to anos an operation. 
For example, GetAsyncKeyState() can determine if the user hit a function key prior to selecting 
an item with the mouse. 


int, The high-order byte is 1 if the key is currently down, 0 if not. The low-order byte is 1 if the key 
was pressed since the last call to GetdsyneKeytate, 0 if not. Use the LOBYTE and HIBYTE . 


macros to retrieve these values (see the example). 
GetKeyboardState(), GetKeyStateQ) 


int: The virtual key code for the key. See Table 7-1, Virtual Key “ee for a complete list, 
WM_KEYDOWN, WM_KEYUP 

This example displays the current status of the shift keys when the “Do It!” menu item is clicked. 
WndProc (CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


hoe ; 
nKeyState ; 


CiMessage) - ; /* process windows messages */ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ ; 
case IDM_DOIT: 
InvalidateRect (hWnd, NULL, TRUE) ; 
UpdateWindow hWnd) 7 /* clear client area */ 
hDC = GetDC (hWnd) ; 
nKeyState = SatdsvncKavstake (VK_! SHIFT) ; 
if (HIBYTE (nKeyState)) 
TextOut (hDC, 10, 10, 
: “Shift is pressed.", 17) ; 
else 
' TextOut (hdc, 10, 10, 
“Shift is not now pressed.", 24) ; 
if (LOBYTE (nKeyState)) 
TextOut (hDC, 10, 30, fen 7 
; "Shift was pressed.", 18) ; 
else : 
TextOut (hDC, 10, 30, 
abit was not pressed before.", 28) ; 
ReleaseDC Chwind, hDC) ; 
break ; 
case IDM_QUIT: : /* send end of application message */ 
DestroyWindow Chind):7 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ;- 
’ break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
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GETINPUTSTATE @Win2.0 eWin30 wWin3.1 


Purpose Determines if there are mouse button, keyboard, or timer events in the message queue. 

Syntax BOGL GetInputState(void); . 

Description - Windows sends messages to the system message queue when the mouse buttons are clicked or 

released, when keys are pressed or releaced, and when a timer is activated. This function checks 
if there are any pending messages from these events at the time the function is called. 

Uses Handy in lengthy calculations to check whether or not the user has pressed a key or the mouse 
button. This may indicate that the user wants to abort the procedure. As GetInputState() does 
not pull the messages off of the input queue, they are still there to be processed by the program’s 
WindProc() function. 

Returns BOOL. TRUE if there are mouse button keyboard,or timer events on the system message queue, 

FALSE if not. , . 

See Also EnableHardwareInput() 

Parameters None (void). 

Related Messages WM_KEYDOWN, WM_KEYUP, WM_TIMER, WM_LBUTTONDOWN 

Example This example sets a one second timer when the user clicks the “Do It!” menu item. Every time 


WM_TIMER message is sent, the GetInputStateQ) function checks for mouse button or keyboar 
input pending in the system message queue. The WM_TIMER events are not detected, a 
GetInputState() is called after the WM_TIMER event is pulled off of the queue and processed. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC 


switch 


hoc ; 
CiMessage) /* process windows messages */ 
case WM_TIMER: - /* Restore mouse and keyboard operation */ 
InvalidateRect (hWnd, NULL, TRUE) ; 
UpdateWindow (hWnd) ; 
hDC = GetDC ChWnd) ; 
if (GetInputState()) 
TextOut (hDC, 10, 10, 
"Keyboard or mouse messages ARE in the queue.", 44) ; 
else 
TextOut ChDC, 10, 10,. 
“NO Keyboard or mouse messages in the queue.", 43) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case WM_COMMAND: : /* process menu items */ 


switch (wParam) 


case IDM_DOIT: /* set timer 1 to every sec. */ 
if (!SetTimer (hWnd, 1, 1000, NULL)) 
{ 


MessageBox (hWnd, "Too many clocks or timers!", 
“Warning”, MB_ICONEXCLAMATION |] MB_OK) ; 


+ 
break ; | ss 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 
} 
break ; 


case WM_DESTROY:/* stop application */ 
KillTimer (hWnd, 1) ; 
PostQuitMessage (0) ; 
break ; 
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default: /* default windows message processing */ 


return DefWindowProc (hWnd, iHessage, wParam, lParam) ; 
} 
return (OL) ; 

} 

GETKBCoDEPAGE mWin20 wWin30 mWin31 

Purpose Finds out which OEM/ANSI keyboard driver table is loaded. 

Syntax int GetKBCodePage(void); ; : 

Description Returns a code for the type of keyboard driver table in use. These drivers are for the characters 
used in different languages. If the file OEMANSI.BIN is in the windows directory when Windows 
is started, the translation table is read and used to create the correct set of characters. 

Uses _For international programs. Use this function to determine which language is in use. Then switch 
to the correct resource data to retrieve the correct text for menus, etc. 

Returns int, the code page currently i in use by Windows. This can be any of the codes in Table 7-7. 


“Defaut USA sane implies that the OEMANSI.BIN file is not in the windows directory. 


437 

850 Intemational (OEMANSI.BIN was copied from XLAT850.BIN when Windows was installed). 

860 Portugal (OEMANSI.BIN was copied from XLAT860.BIN when Windows was instatled). 

861 iceland (OEMANSI.BIN was copied from XLAT861.BIN when Windows was installed). 

863 French Canadian (OEMANSI.BIN was copied from XLAT863.BIN when Windows was installed). 
865 Norway/Denmark (OEMANSI.BIN was copied from XLAT865.BIN when Windows was installed). 


Table 7-7, Keyboard Code Page Values. 


. Parameters None (void). 
Example This simple example just displays the code page value when the “Do It!” menu item is clicked. 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 
HDC hdc ; 
int KBCode ; 
char cBuf £25] > 
switch (CiMessage) , /* process windows messages */ 
case WM_COMMAND: , /* process menu items */ 
switch (wParam) 
case IDM_DOIT: 
KBCode = GetKBCodePage Q : 
itoa (KBCode, cBuf, 10) ; 
hDC = GetDC (hWnd) ; 
TextOut (hDC, 10, 10, cBuf, creer CcBuf)) 3; 
TextOut (hdc, 10, 40, "= Oem Code Table.", 17); 
ReleaseDC (hWnd, hoc) ; 
. break ; 
[Other program lines] . 
GETKEYBOARDSTATE - mWin2.0 mWin30. mWin31 
Purpose Finds out the status of all of the i in one function call. | 
Syntax ~ void GetKeyboardState(BYTE FAR *ipKeyState); 
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Description 
Uses 
Returns 
See Also 


Parameters 
lpKeyState 


Related Messages 
Example 
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Copies the status of all 256 virtual keyboard keys to an array of bytes. 

Reading more than one key’s status. For example, (Smet)-(tn key combinations. 
No returned value (void). . . 
GetInputState(), SetKeyboardState() 


. BYTE FAR *: An array of 256 bytes. Use the virtual key codes listed at the beginning of the 


chapter as indices into the array of key states. After the function is called, a given key’'s byte will 
have the high bit set to 1 if the key is down, or 0 if the key is up. The low bit is set to 1 if the key 
has been pressed an odd number of times, otherwise 0. This is only useful for the keys that toggle 
on and off, such as the and (GéRout Lock) Keys. 


WM_KEYDOWN 


This example checks whether or not the shift key is depressed when any keydown message is 
received. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hDC ; 
static char cKeyduf [256] ; 
switch CiMessage) ; /* process windows messages */ 


Ease WM_KEYDOWN: 


— 
Le 


InvalidateRect thlind, NULL, TRUE) ; 
UpdateWindow chun) 
hOC = GetDC ChWnd) ; 
GetKeyboardState (ekeyBuf) : 
if (cKeyBuf CVK_SHIFTJ & 0x80) 
TextOut (hdc, 10, 40, "Shift key pressed.", 18) ; 
else 
TextOut ChDC, 10, 10, "Shift key NOT pressed.", 22) ; 
ReleaseDC Chuind, hDC) ; 
break ; 


[Other program lines} 


GeTKEYBOARDTYPE OWin2.0 wWin30 mWin3.l 


Purpose 


Returns 


Retrieves the type of keyboard or the number of function keys. 
int GetKeyboardType(int nTypeFlag); 


_ Depending on the value of the nTypeFlag, this function will retrieve either a ‘oi to the type of 


keyboard in use, or the number of function keys on the keyboard. The older PC type keyboards 
had only ten function keys, and they were on the left side of the keyboard. These keyboards also 
had the arrow and numeric keypads superimposed. This forces a few limits when designing a 
keyboard interface, which are not a problem with the newer keyboards. Most programmers avoid 
the issue by not using function keys 11 and 12, and by not creating situations that require simul- 
taneous use of the cursor keys and numeric keypad. 


Determining how many function keys are on the keyboard, and if the direction keys are combined 
on the numeric keypad. 


| int, the keyboard type or. number o of function keys. 


lfnTypeFlag == 0, the returned value is as listed in Table 7-8. 
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Meaning 


IBM PC/XT, or compatible 83 key keyboard. 

Olivetti M24 “ICO” 102 key keyboard. 

IBM AT 84 key keyboard (early ATs). 

IBM Enhanced 101 or 102 key keyboards. 

Nokia 1050 and compatible keyboards. . 

Nokia 9140 and compatible keyboards. we 


Table ‘ g. Keyboard Type Values. 


If nTypeFlag = 1, the keyboard subtype is returned. This is not normally used. 
If nTypeFlag = 2, the number of function keys is returned. 


Oo nnr woO.nM = 


Parameters , 

nTypeFlag int: Set to 0, 1, or 2. Controls if the returned value is the keyboard type, subtype, or number of 
function keys. Normally set to zero to determine if an enhanced keyboard is in use. - 

Example This example displays the type of keyboard and the number of function keys when the user clicks 


the “Do It!” menu item. 
Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . 
HDC . hdc ; 


int nKeyboard, nFuncKeys ; 
char cBuf (5].; 


Switch (CiMessage) /* process windows messages: */ 
{ . ; . ‘ = 
case WM_COMMAND: /* process menu items */ 
switch (wParam) A 
{ 7 ro, 
case IDM_DOIT: . af & mere 


hDC = GetDC ChWnd) ; 

nKeyboard = GetKeyboardTyp2 (0) 
nFuncKeys = GetKeyboardType (2) 
switch (nKeyboard) 

{ 


case 1: 
TextOut (hdc, 10, 10, 
; "PC keyboard.", 12) ; 
break ; ; ; 
= case 3: 
TextOut (hDC, 10, 10, 
“Old AT keyboard.", 16) ; 
break ; 
case 4: ; 
TextOut ChDC, 10, 10, 
Me “Enhanced keyboard.", 18) ; 
break ; “ 


default: 

TextOut (hDC, 10, 10, 
“Unusual keyboard.", 17) ; 

ae break ; . 

} 

itoa (nFuncKeys, cBuf, 10) ; 

TextOut (hDC, 10, 30, cBuf, strlen (cBuf)) ; 

TextOut (hDC, 30, 30, "Function keys.", 14) ; 


break ; ; 
case IDM_QUIT: /* send end of application message ty 
DestroyWindow (hWnd) ; 
break ; 
rae 
-- break ; 
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case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) 
break ; oni a 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
} 
- return (OL) ; 
} 
GETKEYNAMETEXT Win2.0 wWin3.0 mWin3.J 
Purpose Retrieves the name of a key. 
Syntax int GetKeyNameText(LONG lParam, LPSTR lpBuffer, int nSize); 
Description Used in processing of WM_KEYDOWN and WM_KEYUP messages. The /Param pananetee is 
passed to GetKeyNameText(). The function en puts the key description into a character buffer 
~ pointed to by lpBuffer. . 
Uses Handy for making error messages. The [pBuffer character string} is a readable description of the 
. key that was pressed. 
Returns The length of the character string returned. . 
See Also GetInputState() 4 
Parameters ae 
lParam DWORD: This is the 32-bit parameter passed when a WM_KEYDOWN or WM_KEYUP message is 
received. See these message descriptions in Chapter 9, Windows Messages, for a description of 
the meaning of each bit. 
lpBuffer LPSTR: Pointer to the buffer to receive the string name. 
nSize WORD: Specifies the maximum length in bytes for the key name, 


not including the terminating NULL character. 
Related Messages WM_KEYDOWN, WM_KEYUP 


Example This program excerpt shows the key name any time a key i is 

pa pressed. In most cases (the letter and number keys), this is just & 
the letter itself. The function keys are returned as “Fl.” The nu- Figure 7-1. GetKey- 

meric keypad keys are preceded by “Num,” as shown in Figure 7-1. NameText() Example. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC hDC ; 
char cBuf £15] ; 


switch CiMessage) /* process windows messages */ 
{ . 


case WM_KEYDOWN: 
InvalidateRect snags NULL, TRUE) ; 
UpdateWindow ChWnd) ; 
GetKeyNameText UUbaeoue cBuf, 14) ; 
hDOC = GetDC ChWnd) ; 
TextOut (hDC, 10, 10, cBuf, strlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 


break ; 
[Other program lines] 
_GeTKeEySraTe aWin20 oWin30 sWin3l 
_ Purpose - Determines if a key was down when the current message was generated, or if a toggle key wi was 
active. 
Syntax int GetKeyState (int nVertKey); 
Description GetKeyState() allows a key’s status to be determined. 
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Uses Normally used to check the status of the toggled keys: (CAPS LOCK), GROLIER), and (RUMLOCK). 


Returns “int. The status of the key is encoded in two bits. The high-order bit is set to 1 if the key was 


‘depressed when the current message was sent, otherwise 0. The low-order bit is set to 1 if the key 
was pressed an odd number of times. This signifies a toggle key being active. . 


See Also GetInputState(), GetAsyncKeyState() 


Parameters 

— nVertKey int: The virtual key code. See Table 7-1 for the complete list. 
Related Messages WM_KEYDOWN, WM_KEYUP . 
Example . ' This example program fragment shows the name of the key pressed (retrieved by GetKey- 


NameText()). If the aps tock) key is toggled on, the text is printed in capital letters. Otherwise, 
it is printed in lowercase letters, The C runtime library functions strupr() and strlwr() convert 
the characters to upper- and lowercase respectively. AnsiLower() and AnsiUpper() could have 
been used (see Chapter 19, Character Sets and Strings). 


long FAR ‘PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
C 


Hoc hoc ; 
char cBuf. C15] ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_KEYDOWN: 
InvalidateRect Ching, NULL, TRUE) ; /* clear client area */ 
UpdateWindow (hWnd) ; . 
GetKeyNameText (lParam, cBuf, 14) ; /* get key name */ 
if (0x0001 & GetKeyState (VK_CAPITAL)) /* caps lock on?*/ |... 
strupr (cBuf) ; /* all caps */ 
else : ; 
strlwr (eBuf) 3 /* atl power case */ 


hDC = GetDC ChWnd) ; 
TextOut (hDC, 10, 10, cBuf, strlen (cBuf)) ; 
ReleaseDC ChWnd, hoc) ; 


break ; 
[Other program lines] - 
LoaDACCELERATORS eWin20 mWin30 mWin3l 
Purpose Loads the accelerator key combinations from the resource file. | 
Syntax HANDLE LoadAccelerators(HANDLE hJnstance, LPSTR lpTableName); a ; 
Description The accelerator key combinations are defined in the resource RC file. Before they can be used, 


you must use LoadAccelerators() to retrieve a handle to the accelerator table. This handle is 
used in the TranslateAccelerator() function to decode incoming keystrokes that may be in the 
accelerator table. Like menu items, accelerators generate WM_COMMAND messages where the . 
wParam value is set to the accelerator ID value. In most cases, this will be the same ID vane as 
a menu item, allowing the accelerator to duplicate exactly a menu come 


Uses . Accelerators are used for keystroke shortcuts to common functions that might otherwise require 
several mouse actions. Accelerators can be used to generate command messages that do not have 
menu equivalents. The example program gives one case of this action. 


Returns. ~ HANDLE. Returnsa handle to the accelerator table if the function was successful, NULL on error. 
Multiple calls to to LoadAccelerators() continue to return the handle to the accelerator table with- 
out reloading the data. | 


See Also TranslateAccelerator() 
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Parameters 


hInstance 


HANDLE: The instance handle for the program containing the accelerator definitions in its re- 
source data. 


lpTableName LPSTR: A pointer to a character string containing the name of the accelerator table. This is the 


same name given in the ACCELERATORS line of the .RC resource file. 


Related Messages WM_COMMAND 


Example 


/* gener 


Hdefine 
ddefine 
#define 
Hdefine 
Hdefine 
#define 


int 
char 


Long FAR. 


. 4* gener 


This example defines a window with a small menu. The menu items are given keystroke equiva- 
lents in the accelerator table. In addition, a command with the ID value code of NOTMENU is - 
defined that can only be driven by the keyboard accelerator _here is no menu equivalent. In all 
cases, the commands just generate message boxes. As shown in this example the header file . 
contains the define statements for all of the menu and accelerator ID values. 


ic.h */ 


IDM_DOIT 
IDM_TOP1 
IDM_OPT1 
IDM_OPT2 
IDM_QUIT 
NOTHENU 

/* global variables */ 

ghInstance ; 

gszAppName [CJ = "generic" ; 

/* function spntatyaes */ 

PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 


/* menu item id values */ 


Aur Wwn- 


/* a non-menu id value */ 


The resource .RC file defines both the menu and the accelerator table. The first accelerator 
assigns (1rL)-D to the ID value IDM_TOP1. The second and third definitions define the function 
keys F1 and F2 to IDM_OPT1 and IDM_OPT2, respectively. IDM_OPT2 is set to not flash the 
menu item when it is activated (NOINVERT). The END key is equated to the “Quit” menu item ID 
of IDM_QUIT. Finally, 2 non-menu command ID of NOTMENU is assigned to the (4i7)-F1 key 
combination. 


ic.rce */ 


#include <windows.h> 
finclude "generic.h" 


generic 


generic 
BEGIN 


generic 
BEGIN 


ICON generic.ico 


MENU . 
POPUP "&First Menu" 
BEGIN 
MENUITEM “&Display Items (Ctrt-D)", | IDM_TOP1 
MENUITEM "&1st Option (F1)", ‘IDM_OPT1 
MENUITEM SEPARATOR 
: MENUITEM "&2nd Option (F2)", | IDM_OPT2 
END : 8 
MENUITEM "Quit (End key)", IDM_QUIT 
ACCELERATORS 
"Dp", IDH_TOP1, | —*~VIRTKEY, CONTROL 
VK_F1, IDM_OPT1, VIRTKEY 
. VK_F2, v IDM_OPT2, VIRTKEY, NOINVERT 
. VK_END, IDM_QUIT, VIRTKEY 
. VKLF1, NOTHENU, VIRTKEY, ALT 


* 
/END 


LoadAccelerators() is used before the program’s message loop in WinMain( to retrieve a 
handle to the accelerator table. The message loop is also modified to include the Translate- 
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Accelerator() function. Note how the NOTMENU item is treated just like a menu ID in the mes- 
sage processing logic, even though it is only defined in the accelerator table. 
/* generic.c accelerator table demonstration */ 


#include <windows.h> 
#include SEEDED TES h" 


int PASCAL WinMain (HANDLE hInstance, HANDLE hPrevinstance, LPSTR LpszCmdLine, 
int nCmdShow) 


t 
HWND hWnd ; 
“MSG i msg ; 
WNDCLASS wndclass ;° 
HANDLE hAccel ; 
ghInstance = hInstance ; — /* store instance handle as global var. */ 
_if (C!hPreviInstance) 
o 
wndclass.style = CS_HREDRAW | CS_VREDRAW ; 
wndclass.lpfnWndProc = WndProc ; 
wndclass.cbClsExtra =0; 
wndclass.cbWndExtra =0; ; 
wndclass.hInstance = hInstance ; 
wndclass.hIcon = Loadicon (hInstance, gszAppName) ; 
wndclass.hCursor = LoadCursor (NULL, IDC_ARROW) ; 
wndclass.hbrBackground = GetStockObject (WHITE_BRUSH) ; 
wndclass.lpszMenuName = gszAppName ; 
wndclass.lpszClassName = gszAppName ; 
_ /* register the window class.*/ 
if C'!RegisterClass (&wndclass)) 
return FALSE ; 
'} 
hWnd = CreateWindow ¢ /* create the program's window here */ 
gszAppName, — /* class name */ 
gszAppName, ‘/*® window name */ 
WS_OVERLAPPEDWINDOW, /* window style */ 
CW_USEDEFAULT, /*® x position on screen */ 
CW_USEDEFAULT, /* y position on screen */ 
CW_USEDEFAULT, /* width of window */ 
CW_USEDEFAULT, /* height of window */ * 
NULL, . /* parent window handle (null = none) */ 
NULL, /* menu handle (null = use class menu) */ 
hinstance, /* instance handle */ 
NULL) ; :  /*® Upstr Cnull = not used) */ 
ShowWindow (hwnd, n¢mdshow) *7 
UpdateWindow (hWnd) ; ' /* send first WM_PAINT message */ 
hAccel = igadkecelanstore ChInstance, gszAppName) ; 
while (GetMessage. (&msg, NULL, 0, 0)) - /* the message loop */ 
{ . * ; 
if (!TranslateAccelerator (hWnd, hAccel, &msg)) 
{ ; 
-TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} ; 
} 
return msg.wParam ; 
} 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iNessage, WORD wParam, LONG lParam) 
tc . 


Seinen CiMessage) -  -/* process windows messages */ 
{ if! : 
i / ease WM_COMMAND: /* process menu items */ 
HOSE switch (wParam) 
{ 


‘case IDM_TOP1: 
MessageBox (hWnd, 
"The top menu item was activated.” 


+ 
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“Code IDM_TOP1", MB_OK) ; 
break : / : 
case IDM_OPT1: 
MessageBox (hWnd, 
“The second menu item was activated.", 
“Code IDM_OPT1", MB_OK) ; : 
break ; 
case IDM_OPT2: 
MessageBox (hWnd, 
“The third menu item was activated.", 
“Code IDM_OPT2", MB_OK) ; 
break ; 
case NOTMENU: 
MessageBox (hWnd, 
“This command activated only via an accelerator.", 
“Code NOTMENU", MB_OK) ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop applicacion */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


} 


‘MapVirTuALKey OWin2.0 mWin3.0 ms Win3.1 


Purpose 
‘Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
wCode 


wMapType 


Converts between virtual key codes, ASCII, and scan codes. 
WORD MapVirtualKey(WORD wCode, WORD wMapType); 


This function performs three separate operations, depending on the value set for wMapType. 
One is the conversion of a virtual key code used in Windows messages to the computer’s OEM 
scan code. (The OEM scan code is the numeric value assigned to each physical key that is re- 
turned at a low level through the computer’s ROM BIOS functions.) The second mode does the 
reverse: converts from OEM scan code to the virtual key code used by Windows. The third mode. 
converts virtual key codes to ASCII values. 


The most common use is to convert the virtual key code used in Windows messages to ASCII 
values that can be printed on the screen. You may find yourself dealing with the OEM scan codes 
in rare cases, such as destinguishing between the left and right keys (both generate the 
same virtual key code). . 


WORD, the value returned depends on wMapType, explained below. 
OemKeyScan() . 


(=[-egenenie. = [> [= 
2 
30 =scancode. | 
65 = ASCIl. 


WORD: The virtual key code to translate ifwMapType is 0 or 2. 
This value is normally obtained from the wParam parameter 
received when a WM_KEYDOWN or WM_KEYUP message is in- 
terpreted. If wMapType is 1, wCode is the OEM scan code to 
translate. See Chapter 9, Windows Messages, for a description 
of how the keyboard data is encoded with the messages. 


- WORD: Specifies the type of translation to do. The values are Figure 7-2. MapVirtualKey() 


shown in Table 7-9. Example. 
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Value Meaning — 


0 wCode is a virtual a code. Mapvitualkey ) returns the corresponding OEM scan code for the same a 


1. _wCode is an OEM scan code. MapVirtualKey() retums the corresponding virtual key code for the same key. 
2 wCode is a virtual key code. MapVirtualKey() retums the corresponding ASCII value. 


Table 7-9, MapVirtualKey() Codes. 


Related Messages WM_KEYDOWN, WM_KEYUP, WM_CHAR — 


Example This code fragment shows two uses of the MapVirtualKey() function. The virtual key code is en- 
coded in the wParam parameter when the WM_KEYDOWN message is received. MapVir- 
tualKey() is used to convert the virtual key code to the OEM scan code and the ASCII value. The 
picture below shows the window after the “A” key was pressed. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC hoc ; 
WORD wCode ; 
char | cBuf £10) ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_KEYDOWN: : 


InvalidateRect (hWnd, NULL, TRUE) ; 
UpdateWindow (hWnd) ; 

hDC = GetDC ChWnd) ; 

wCode = MapVirtualKey cereram, 0) ; 

itoa (wCode, cBuf, 10) ; 

TextoOut (hDC, 10, 10, cBuf, strlen CcBuf)) 7 
TextOut (hDC, 50, 10, "= scan code.", 12) ; 
wCode = MapVirtualKey (wParam, 2) ; 

itoa (wCode, cBuf, 10) ; . 

TextOut (hDC, 10, 30, cBuf, strlen (cBuf)) ; 
TextOut (hDC, 50, 30, "= ASCII.", 8) ; 
ReleaseDC (hWnd, hoc) ; 


‘break ; 
[Other program lines] 
OreMKEYSCAN | —- OWin2.0 8Wind0 Wind 
_ Purpose - Converts from ASCII to the Keyboards OEM scan code. 
Syntax DWORD OemKeyScan(WORD wOemChar); 
Description The OEM scan code is part of the Param message accompanying every WM. KEYDOWN and 


WM_KEYUP message. OemKeyScan() allows you to get the OEM keyboard scan code that 
matches an ASCII character. 


" Uses Used in sending other Windows messages that simulate keypresses. This can be an efficient way 
to pass information between windows that already have message processing logic to handle key- 
board input. 

Returns _. DWORD, the OEM scan code in the low-order WORD. The high-order WORD has bit | set to 1 ifa 


key must be pressed to generate the letter, and bit 2 set to 1 if the key must be - 
pressed. If there is no OEM equivalent to wOemChar, —! is returned in both the high-order and 


low-order WORDS. 
See Also _ VkKeyScan (), MapVirtualKey() 
Parameters 4 
wOemChar WORD: The ASCII value to convert. 


Related Messages WM_KEYDOWN, WM_KEYUP 


A 
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Example In this case, there is a popup window (illustrated in Figure 7- 
3) which has its own message processing function. When the 
popup has the input focus, any keypress results in the key’s 
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ASCII letter being displayed in the popup’s client area. Ifthe {§ 
user Clicks the “Do It!” menu item, the parent window sends Boe 


the popup a simulated WM_KEYDOWN message, with both 
wParam and lParam set to match the letter “A” key. This is a 
miniature example of how windows can communicate with 
each other without necessarily adding extra program logic to 


decode the messages. 


Figure 7-3. OemKeyScan() 


Because the child window has its own message procedure, — Example. 
the procedure name must be added to the EXPORTS section of 
the program’s .DEF definition file and declared in the header file. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC hoc ; 

static WNDCLASS wndclass ; 
static HWND . hPopup ; 
WORD ; wVirtKey ; 
DWORD dwOemField ; 


switch (iMessage) 
{ 


case WM_CREATE: 
wndclass.style 


= CS_HREDRAW | CS 


wndclass. lpfnWndProc 
wndclass.cbClsExtra 
wndclass.cbWndExtra 
wndclass.hInstance 
wndclass.hIcon 
wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.lpszClassName 


/* device context handle */ 
/* the window class */ 


/* process windows messages */ 


/* build popup window as program starts */. 


VREDRAW | CS_PARENTDC ; 
ChildProc ; 

0; 

0; 

ghInstance ; 

NULL ; 

LoadCursor (NULL, IDC_ARROW) ; 
GetStockObject (LTGRAY_BRUSH) ; 
NULL ; 

"SecondClass” ; 

/* register the window class */ 


nun aenvr wa 


if(RegisterClass (&wndclass)) 
{ 


hPopup = CreateWindow ("SecondClass", “Popup Window", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 50, 200, 150, hWnd, NULL, ghInstance, NULL) 
ShowWindow (hPopup, SW_SHOW) ; 


} 
break ; 


case-WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* send popup window a fake keypress */ 
wVirtKey = -VkKeyScan (CCWORD) 'A') >; 


dwOemField = 


((OemKeyScan 


CCWORD) 'A') & OxOOFF) << 16) | 1; 


SendMessage (hPopup, WM_KEYDOWN, wVirtKey, dwOemField) ; 


break ; 
case IDM_QUIT: 


/* send end of application message */ 


DestroyWindow (hWnd) ; 


break ; 
} ; 
break ; 


case WM_DESTROY: . /* stop application */ 


PostQuitMessage (0) ; 
break ; 


default: /* default windows message processing */ 
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return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
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} 


return COL) ; 


} 


/* Here is a separate message processing procedure tor the popup window */ 
Long FAR PASCAL ChildProc CHWND hWnd, unsigned iMessage, wURD wParam, 
LONG lParam) 


{ 
HDC 
char 


switch 
{ 


} 


hDC ; 
cBuf C2] ; 


(iMessage) /* process windows messages */ 


case WM_KEYDOWN: 
InvalidateRect Chind, NULL, TRUE) ; 
UpdateWindow ChWnd) ; 
hDC = GetDC (hWnd) ; 
TextOut (hDC, 10, 10, "Keypress Received:", 18) ; 
cBuf CO] = (char) MapVirtualKey (wParam, 2) ; - 

~ - TextOut (hdC, 10, 30, cBuf, 1) ; 

Relegsele ChWnd, hDC) ; 
break ; 

default: /* default windows message processing */ 
return ‘DefWindouProe ChWnd, iMessage, wParam, (Param) ; 


return (OL) ; 


} 


-SETKEYBOARDSTATE  mWind.0 = mgWin80 mWin31 


Purpose 
Syntax 
Description 


Returns 
See Also 


Parameters 
lpKeyState 


Related Messages 
’ Example 


Sets the keyboard status for all 256 virtual keys in one function call. 

void SetKeyboardState(BYTE FAR *IpKeyState); 

The status of all 256 virtual keys is held in an array of bytes pointed to by the lpKeyState param- 
eter. In each of these bytes, the high-order bit is set to 1 if the key is down, and the low-order bit 
is set to 1 if the key has been pressed an odd number of times. The latter is useful for the toggle © 
keys such as (CAPStOck) and (NUMLOCK). Generally this function is used after calling GetKey- 
boardState() to retrieve the current keyboard status, Individual values can be changed in the 256 
byte data array, and then sent back to Windows by calling SetKeyboardState(). 

Used to change the Guirr tock), (NUMLOCK), and key states. These have the virtua! key 
codes of VK_CAPITAL, VK_NUMLOCK and VK_OEM_SCROLL, respectively. To set one of these 
toggle keys on, use a value of 0x81 in the 256 byte array. To set a nontoggle (normal) key on, use 
a value of 0x80. The virtual key code is the index to the item in the array. For example, to set the 
shift lock item ON in a buffer called cVKBuf[256], use 

cVKBuf CVK_CAPITALI = 0x81 ; as 

No returned value (void). 


GetKeyboardState() 


BYTE FAR *:; A pointer to an array of 256 bytes. Generally, initialized to the current keyboura 
status by calling GetKeyboardState() prior to changing values. 


WM_KEYDOWN, WM_KEYUP, WM_CHAR 


This WndProc() function toggles the ars tock) ne on and off when the user clicks the “Do It!” 
menu item. 


long FAR PASCAL WndProc CHWND hWe:d, unsigned iMessage, WORD wParam, LONG LParam) 
{ . 


HDC 


hDC ; 
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cKeyBuf [£256] ; 


static BOOL bCapsOn 


switch (iMessage) /* process windows messages */ 
{ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_DOIT: 
InvalidateRect (hWnd, NULL, TRUE) ; 
UpdateWindow ChWnd) ; . 
hdC = Get&C ChWnd) ; 
-GetKeyboardState (cKeyBuf) ; /* read all VK_ values */ 
if (CcKeyBuf CVK_CAPITALI) & 0x01) 
{ 


cKeyBuf CVK_CAPITALI] = 0 ; /* shift lock off */ 
TextOut (hdc, 10, 40, 
“Shift key NOT pressed.", 22) ; 


} 
else 
{ < 
; cKeyBuf CVK_CAPITALJ = 0x81 ; /* shift lock on */ 
TextOut (hDC, 10, 10, 
“Shift key pressed.", 18) ; 
} 
SetKeyboardState (cKeyBuf) ; /* set all VK_ values */ 
ReleaseDC (hWnd, hOC) ; 
break ; ; ; 


case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
} 
return (COL) ; 

} 

TRANSLATEACCELERATOR . Win2.0 mWind.0 gWin3d1 

Purpose Translates keystrokes into commands using the accelerator table. 

Syntax int TranslateAccelerator(HWND hWnd, HANDLE hAccTable, LPMSG [pMsq); 

Description Accelerator key combinations are defined in the ACCELERATOR portion of the resource .RC file. 
Prior to using the accelerator table, use LoadAccelerators() to retrieve the handle to the table. 
TranslateAccelerator() is used within the program's message loop to convert from the keystrokes 
entered to the command specified in the accelerator table. 

Uses Accelerators are used to provide keystroke shortcuts for menu commands. They can also be used 


to send command messages to the system that do not have keyboard equivalents. 

If TranslateAccelerator() returns a nonzero value, it has successfully translated the key- 
stroke and sent the command to the program’s message processing function. The application 
should not allow the normal TranslateMessage() and DispatchMessage() functions to process 
the keystrokes again. To avoid this, use the following structure for the program’s message loop in 
WinMain(). . 


while (GetMessage (&msg, NULL, 0, 0)) /* the message loop */ 
{ 


if (!TranslateAccelerator ChWnd, hAccel, &msg)) 
{ 
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Returns 
See Also 


Parameters 
hWnd 


hAccTable 
lpMsg 


TranslateMessage (&msqg) ; 
DispatchMessage (&msg) ; 


When an accelerator is translated, the message is sent directly to the program's message 
processing function, bypassing the message queue. The accelerator ID value is sent as the 


_ wParam parameter of either a WM_COMMAND message (normal case) or a WM_SYSCOMMAND 


message (if the ID value is one of the system menu ID values SC_RESTORE, 8C_ MOVE, SC_ SIZE, - 
SC_MINIMUM, SC_MAXIMUM, SC_CLOSE). 


int, TRUE if a keystroke entry was translated into an accelerator command, FALSE if not. 
LoadAceelerators() 


HWND: The handle of the nog with a message penceesine function (WinProc()) which is to 
receive the translated messages. 
HANDLE: The handle to the accelerator table retrieved with LoadAccelerators(). 


LPMSG: A pointer to a message structure. This structure holds the message data received when 
GetMessage() was called. 


Related Messages WM_COMMAND, WM_SYSCOMMAND 


Comments 


Example 


VkKeryScan 


Purpose 
- Syntax 
Description 


Uses 


You can determine if a command message was sent via a menu selection or accelerator by exam- 
ining the [Param parameter when the program receives a WM_COMMAND or WM_SYSCOM- 
MAND message. If the high-order word of [Param is one, the message came from an accelerator 
table translation. Because of the hWnd parameter, TranslateAccelerator() sends messages to 
the message processing function of the main window (the window with the handle hWnd), and 
not to child windows that have separate message processing functions. 


See the example under the LoadAccelerators() function description. 


ta Win 2.0 Win 3.0 Win 3.1 
Translates an ANSI character to the corresponding virtual key code. 
int VkKeyScan(WORD cChar); 


The returned value contains the VK_ code in the low-order byte and GHiFT) Ga key information in the 
high-order byte. 


Sending WM_KEYDOWN and WM_KEYUP messages to other windows. This can be an efficient 


‘way to pass information between windows if the receiving window already has keyboard input 


logic in its message processing (WinProc()) function. 


int. The virtual key code is in the low-order byte returned. The shift state | is encoded in the high-. 
order ee as. shown in Table 7-10. 


ies os Meaning 
No shifted on. 

The character is shifted with either of the GHIFT) keys. 
The character is a contro! character. 


A key combination that is not used for characters. 
The (CTRL)-(ALT) key combination. 
The (GHIFT)-(CTRL)-(ALT) key combination. 


Table 7-10. ViKeyScan() Codes. 
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See Also OemKeyScan(), MapVirtualKey() 
Parameters , 
‘cChar char: The ANSI char vaiue to be translated into a virtual key code. 
Related Messages WM_KEYDOWN, WM_KEYUP 
Example See the example under the OemKeyScan() function description. 
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Message handling is the biggest difference between programming under Windows and programming under a more 
conventional environment, such as DOS. There is no real equivalent to a message in the DOS world. Message process- 
ing is the basic concept behind Windows’ ability to run several applications at the same time, and allow the user to 
easily switch between them. Most programs only use the most basic message functions: a message loop in WinMain() 
and a series of actions based on received messages in the WndProc() function. Significantly more control over mes- 
sage processing is possible. Messages can be intercepted and modified by hook functions, prior to being passed to the 
program. Separate programs can also communicate with 

each other by exchanging messages as they operate. s as 


Message Flow. 
Figure 8-1 shows a simplified diagram of a message be- 


Program Message Queue 


dng processed by a Windows program. Windows loads ee Ae ft PRES es Hook Function | 
low-level functions for dealing with the keyboard, mouse, s sar rmenere SRE om 

and screen when Windows starts. When a hardware TranslateMessage() 3 

event such as a keystroke occurs, Windows sends a mes-  fSitmerpenry hey eso ree 5 

sage to the active program’s message queue. The mes- os oa 


sage queue is just a memory location to hold message 
data that has not yet been processed by the running pro- 
gram. . 

The “message” is actually a small data structure de- 
fined in the WINDOWS.H header file. 


/* Message structure */ . 
typedef struct tagMSG : ‘ 
{ 


: WndProc{ ) Function 


HWND hwnd; 
WORD message; / 
WORD wParam; 
LONG lParam; 
DWORD time; 
POINT pt; 
+ MSG; : 
typedef MSG *PMSG; 
typedef MSG NEAR *NPMSG; 
typedef MSG FAR ; *LPMSG; 


The message data contains the window handle (hwnd), the coded message type (message), the wParam and 
lParam data that will be passed to the WndProc() function, the time the message was sent (in milliseconds after 
Windows started), and a POINT structure containing the X and Y location of the mouse cursor when the message was 
sent (pt). The cursor location is given in screen coordinates (pixels from the upper left corner of the screen). When 
most programmers talk about a “message,” they usually are referring just to the message element in the MSG struc- 
ture. This is a value, such as WM_PAINT or WM_KEYDOWN defined in WINDOWS.H. Keep in mind that the real 
message stored in the application’s message queue is in the form of the MSG data structure. 
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Processing Messages 


An application program pulls messages off the message queue in the “message loop” at the bottom of the WinMain() 
function. Message loops typically have the form 


while (GetMessage (&msg, NULL, 0, 0)) /* putls messages from message queue */ 
{ 
TranslateMessage (&msg) ; /* translates keyboard messages to WM_CHAR */ 
DispatchMessage (&msg) ; /* sends the message to WndProc() function */ 
} , 


The GetMessage() function fetches the message and can give control to other programs if there are no messages 
to process. GetMessage() is followed by TranslateMessage() and DispatchMessage(). DispatchMessage() sends the 
message data to the WndProc() function you write to handle the program's logic. DispatchMessage() knows which 
function should receive the messages because you defined the message function in the window’s class definition. 

TranslateMessage() is a utility function that takes raw input from the keyboard and generates a new message 
(WM_CHAR) that is placed on the message queue. The message with WM_CHAR contains the ASCII value for the key 
pressed, which is easier to deal with than the raw keyboard scan codes and virtual key codes. You can leave 
TranslateMessage() out if you will not be directly processing keystrokes. 

The program's WndProc() function typically deals only with a few of the 250 Windows messages. Depending on 
the program, messages for menu items, mouse movements, or keyboard input may be important, or ignored. Those 
that are not processed by the WndProc() logic are passed to the default message handling function, DefWindowProc(), 
shown at the bottom of Figiire 8-1. 


Program Control 


Ifyou build a long calculation into the body of a Windows program, it will not be possible to switch to another program 
while the program is calculating. The program is said to “have control” of the Windows environment. This is clearly not 
how Windows programs should behave. Users expect to be able to switch between applications quickly. Perhaps the 
single most critical concept to understand about a Windows program is that Windows programs are not interrupted. 
Windows programs must be designed to give up control frequently so that other programs have a chance to operate. 
(There is one exception to the “no interrupts” statement. When Windows runs a DOS application in 386 mode, the 
DOS application is handled via interrupis.) 

There are only three functions that give up control: GetMessage(), PeekMessage(), and WaitMessage(). Of these, 
GetMessage() is used most frequently. The difference between these three is in how actively they attempt to keep 
control of the system. GetMessage() is the most active, and it will keep control until it empties out the application 
program’s message queue, PeekMessage() gives uv control as soon as it is called, and it gets control back only if other 
applications run out of messages to process. WaitMessage() gives up control as soon as it is called and will not recover 
control until a message within a certain range is found on the program’s message queue and all other applications 
have run out of messages to process. Any program that will remain running under Windows for a length of time must 
call one of these three functions to allow Windows to pass control between applications. 

One way to think about this situation is to imagine the opposite: a Windows program that never gives up control. 
These are easy to create (too easy). Just put all of the 
program logic in the WinMain() function, and eliminate 
the message loop. Once the program is started, no other 
Windows application will be able to run until the pro- 
gram quits. 


Sources of Messages 


Figure 8-1 provides a simplified flow diagram for a single 
message from the mouse or keyboard flowing through =| vfs 
the messaging logic. There are a few more possibilities : 
for how a message might originate. Figure 8-2 shows ‘= a 
more detail surrounding the program’s message loop. Figure 8-2. Messages Tutoring the Atos ison. 
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Messages do not all start from hardware actions. You may find it convenient to send a program messages from 
within the body of the program. This is frequently done in place of using a goto: statement. The messages can be sent 
either to the program’s message queue with PostMessage() or directly to the WndProc() function with © 
SendMessage(). Experienced programmers use PostMessage() and SendMessage() within a program as an alterna- 
tive to goto: statements. Another reason to send a message from within a program is to request repainting of the 
window’s client area. This is such a common request that a shorthand version of SendMessage() is provided just for 
this purpose. UpdateWindow() sends a WM_PAINT message directly to the program’s WndProc() function, bypassing 
the message queue. Whether or not a message is queued is not normally important to writing a Windows program 
Your WndProc() function will deal with both types of messages in the same way. 

Other programs can also send messages to running applications. These are often specialized messages, unique to 
a group of programs. Windows provides RegisterWindowMessage() to generate unique message codes while the pro- 
grams are running. The codes are sequenced so as to not overlap other message numbers used by unrelated programs. 
There is a standard protocol for exchanging messages between running programs called “dynamic data exchange” 
(DDE), which is covered in Chapter 30. 


Reentrant Functions 


Messages are not like interrupts. Windows will not jump in and halt the execution of a program to go to some more 
critical task. For example, if a calculation is still running after a menu item is clicked, you do not have to worry about 
calculation being stopped half way through because a new message is received. Windows will not be able to pass 
another message to your program until the calculation is done and the execution returns to the message loop for 
another call to GetMessage(). One situation that will start a message from within your function’s calculation is if the 
program uses a Windows function that sends a message, bypassing the message queue. For example, if SendMessage() 
is called from within the calculation, the message sent will go directly to the WndProc() function and will be acted 
upon before the rest of the calculation has completed. 

If WndProc() generates messages to itself, WndProc() is said to be a “reentrant.” Message handling functions, 
such as WndProc() are reentrant. A key consideration is to avoid having two parts of the function send each other 
_ messages. This can set up an infinite loop of messages, hanging the system. This typically occurs in situations where a 
scroll bar control changes an integer in an edit control, and changing the integer in the edit control adjusts the same 
scroll bar. You can make this work, but it peut designing the functions so that messages are not sent after the first 
adjustment. 


Message Hook Functions 


Windows provides an almost ultimately powerful set of functions that allow setting message “hooks.” Hooks allow a 
module (running program or DLL) to intercept messages going to other applications. The messages ci: be acted on, 
modified, or even stopped. A typical example of a use for a hook function would be to remap the keyboard. Every 
keyboard message could be intercepted, and then modified to reflect a different keyboard layout. More sophisticated 
uses are to modify the behavior of specific applications. For example, you could write a hook function that intercepts 
WM_SIZE and WM_MOVE messages for a program, forcing the application to always be located at one spot and one 
size on the screen. Still another use is to record and playback Windows messages, for recording repeated actions 
- (macros). There are seven different types of hook functions defined, each with its own special purpose. The 
SetWindowsHook() installs the hook function into Windows, while UnhookWindowsHook() removes it. The 
DefHookProc() function is provided to pass messages not acted on by the hook function back on to their next destina- 
tion. Hook functions can be chained in series. This allows a series of modifications to various messages to be carried 
out at one time. 

Hook types require that the hook function be in a dynamic link library (DLL). DLLs are not covered in this book 
‘until Chapter 28, Dynamic Link Libraries. However, they are simple to create, and the examples in this chapter show 

the changes need to be made in the C, NMAKE, and .DEF definition files to create DLLs. 

When writing the DLL for a message hook, you will generally write four functions. LibMain() is the standard entry 
point for a DLL, just like WinMain() for an application program. Write a “SetHook()” function to install the message — 
hook in Windows. Add a “FreeHook()” function to remove the hook. It is inside these two functions that the Windows 
SDK functions SetWindowsHook() and UnhookWindowsHook() are called. Finally, write the actual message filter 


—_ : 
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function that acts on the message, or just passes it on to DefHookProc(). The example under the SetWindowsHook() 
function description provides a complete listing. Hook functions are so powerful that extreme care must be taken in 
using them. Use should be restricted to utility functions and custom modifications of existing applications where the 
source code is not available. In normal Windows programming, you will have direct control of the message processing 
logic and will have little need for message hooks. 


Cautions 


Any time GetMessage(), PeekMessage(), or WaitMessage() is called, Windows has the option of passing control to 
another application. This will cause local variables and stored far memory addresses to become invalid. More on this 


in Chapter 14 on memory management. 


Message Function Summary 


Table 8-1 summarizes the Windows message processing functions. The detailed function descriptions follow immedi- 
ately after the table. 


Function 


‘Purpose 


Activate a message filter (hook) function. 


CallMsgFilter 
CallWindowProc Pass message parameters to a message processing function. - 
DefHHookProc Provide default message processing for message hook functions. 
DefWindowProc Provide the default processing for Windows messages. 
DispatchMessage Send a Windows message to the program’s WndProc\() function. 
ExitWindows Exit the Windows environment to DOS. 
FreeProcinstance Decouple a procedure instance from a data segment. 
GetMessage Retrieve a message from Windows, or give control to another application if no messages are 
, waiting for the windcw currently receiving messages. 
GetMessagePos ~ Retrieve the X,Y position of the cursor when a message was sent. 
GetMessageTime Retrieves the time value when a message was sent. 
InSendMessage Determine if the current message being processed was sent by SendMessage(). 
MakeProcinstance Provide a procedure-instance address for a function. — 
PeekMessage Check the message queue for a message. 
-PostAppMessage Put a message in the application program’s message queue. 
PostMessage Put a message on a windows message queue. 
PosiQuitMessage Shutdown an application. 
RegisterWindowMessage Create a new, unique Windows message number. 
ReplyMessage Free the application sending a message to continue to execute. 
- SendMessage Send a Windows message directly to a window's message function. 

. SetMessageQueue Change the size of an application's message queue. 
SetWindowsHook Install a Window’s message filter function. Installs a Window's message filter function. 
TranslateMessage Generate WM_CHAR, WM_SYSCHAR, WM_DEADCHAR, and WM_SYSDEADCHAR messages 

when a virtual key code is received.. 

UnhookWindowsHook Remove a message hook function from the system. 
WaitMessage Yield control to any other application when a message is received. 


Table 8-1. Message Processing Function Summary. 
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/* generic.c */ 


'CaLtLMsGFILTER . Win2.0 mWin3.0 mWin3.1 

Purpose Activates a message filter function. 

Syntax BOOL CallMsgFilter(LPMSG lpMsgq, int nCode); 

Description ~ ‘This function passes a message to a message function. The message function must be of the type 
WH_MSGFILTER, loaded with SetWindowsHook(). The nCode parameter allows the calling pro- 
gram to change the type of processing done within the filter depending on the value of nCode. 

Uses Modifying the messages intercepted, or doing an operation from within the hook function as 

. messages are received. 

Returns BOOL. TRUE if the message should be aaa further, FALSE otherwise. 

See Also SetWindowsHook(), UnhookWindowsHook() | 

Parameters 

lpMsq LPMSG: A pointer to a MSG data structure. This i is the message that will be filtered by the filter 
function. 

nCode int: Specifies a code value to control what the filter does. The values between —2 and 8 are 
defined in WINDOWS.H for special purposes. A good practice is to use values of un USER and 

integer values above it (WM_USER + 1, etc.). 

Related Messages Only messages processed by a WH_MSGFILTER type of filter function will be passed. This in- 
cludes WM_PAINT messages and messages from menus, dialog boxes and message boxes. See 
SetWindowsHook() for details on the hook function. . 

Example This example sets a hook function from within WinMain(). The hook is activated only if the user 


clicks the “Do It!” menu item. The hook function is called from within the program’s message loop 
using CallMsgFilter(). The hook function is defined below (in a DLL). The hook is coded so action 
is taken only if the 2Code parameter is set to WM_USER. This assures that the hook only works 
when the CallMsgFilter() requests it. The following code constitutes the main program. 


#include <windows.h> 
Hinclude "“generic.h" 


BOOL bFilterIt = FALSE; /* globals */ 
BOOL bHooked = FALSE ; 


int PASCAL WinMain (HANDLE hInstance, HANDLE hPrevinstance, LPSTR LpszCmdLine, int nCmdShow) 
{ : ‘ 


HWND hWnd ; 
MSG msg ; 
WNDCLASS wndclass ; 
ghInstance = hInstance ; /* store instance handle as global var. */ 
if (!hPrevInstance) /* load data into window class struct. */ 
wndclass.style = CS_HREDRAW | CS_VREDRAW ; 
wndclass.lpfnwWndProc = WndProc ; 
wndclass.cbClsExtra =O;.- 
wndclass.cbWndExtra =O; 
wndclass.hInstance ~ = hInstance ; 
wndclass.hIcon = LoadiIcon (hInstance, gszAppName) ; 
wndclass.hCursor = LoadCursor (NULL, IDC_ARROW) ; 
wndclass.hbrBackground = GetStockObject (WHITE_BRUSH) ; 
wndclass.lpszMenuName = gszAppName ;° 
wndclass.lpszClassName = gszAppName ; 
/* register the window class */ 
if (!'RegisterClass (&wndclass)) 
return FALSE ; 
} 
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hWnd = CreateWindow (¢ /* create the program's window here */ 
gszAppName, /* class name */ 
gszAppName, /* window name */ 
WS_OVERLAPPEDWINDOW, /* window style */ 
CW_USEDEFAULT, /* x position on screen */° 
CW_USEDEFAULT, /* y position on screen */ 
CW_USEDEFAULT, /* width of window */ 
CW_USSDEFAULT, /* height of window */ 
NULL, /* parent window handle (null = none) */ 
NULL, . /* menu handle Cnull = use class menu) */ 
hInstance, /* instance handle */ 


NULL) ; /* 
ShowWindow Chyind, nCmdShow) ; 
UpdateWindow (hWnd) ; 


tpstr Crull 


if (SetHook C"MsgFilterFunc", WH _MSGFILTER)) 
bHooked = TRUE ;° 


while (GetMessage (&msg, NULL, 0, 0)) 


{ 
if (bHooked & bFilterIt) , 
: CallMsgFilter (&msg, WM_USER) ; 
TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} 


FreeHook ("msgFilterFunc", WH_MSGFILTER) ; 
return msg.wParam ; 


not used) */ 


/* send first WM_PAINT message */ 


/* the message loop */ 


/* if desired... */ 
/* filter messages */ 


Long. FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam). 


{ 
switch (iMessage) /* process windows messages */ 
{ é 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: 
if (bFilterIt) 
{ 
bFilterIt = FALSE ; 
MessageBox (hWnd, “Hooked function not active.", 
"Message", MB_OK) ; 
} 
else 
{ 
bFilterIt = TRUE ; 
MessageBox (hWnd, “Hooked function Active.", 
“Message”, MB_OK) ; 
} 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 
} 
break ; : ; ; 
case WM_DESTROY: / /* stop application */ 
PostQuitMessage (0) ; 
break ; . 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
} 


return COL) ; 
Note that the hook function is created in a dynamic link library (DLL). Creation of DLLs 


requires special compiler settings and changes to the .DEF definition files. See the Set- 
WindowsHook() example for a complete listing. Note in this case that the hook function simply 
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makes the computer beep every time a WM_PAINT message is mecelven: More complex opera- 
tions could be done in processing the message. 


/* msgdtl.c Library of message filters */ 
/* *] ; 


#Hinclude <windows.h> 


HANDLE . hInstanceDLl ; 
FARPROC LpOLdHook ; 


int FAR PASCAL LibMain (HANDLE hinstance, WORD wDataSeg, WORD wHeapSize, 
LPSTR lLpszCmdLine) 


{ 
if (wHeapSize > 0) 
UnlockData (0) ; 
hInstanceDLlt = hInstance ; 
return (1) ; 
} 


BOOL FAR PASCAL SetHook (LPSTR LpsHookName, int nHookType) 
{ 
FARPROC lpHook ; 


LpHook = GetProcAddress ChInstanceDLll, lLpsHookName) ; 
if (LpHook) 


{ 
LpOldHook = SetWindowstodk (nHooktype, t tpHeok) ; 
return (TRUE) ; - 

} 

else 


return (FALSE) ; 
} 
BOOL FAR PASCAL FreeHook (LPSTR LpsHookName, int nHookType) 7 
: FARPROC , tpHook ; 


lpHook = GetProcAddress ChInstanceDLl, lpsHookName) ; 
return (UnhookWindowsHook (nHookType, LpHook)? ; 


ft 


} 1 
int FAR PASCAL MsgFilterFunc Cint nCode, WORD wParam, DWORD LParam) 
LPMSG : . msg ; 
if (nCode != WM_USER) 
DefHookProc (nCode, wParam, lParam, &lpOldHook) ; 
else 
{ . 
msg = (LPMSG) LParam;  /* lParam holds message address */ 
if (msg->message == WM_PAINT) 
{ ; : 
MessageBeep (0) ; 
return (TRUE) ; 
} 
} ‘. 
‘ return (FALSE) ; 
} 
~CaLLWINDOWPROC  mWin2.0 wm Win30 mWin3.1: 
Purpose Passes message parameters to a message processing function. 
Syntax . LONG CallWindowProc(FARPROC ipProvWadFunc, HWND hWnd, WORD wMsg, WORD 


wParam, LONG farem); 
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Description This function is used commonly within a window subclassing function. Subclassing is used to add 
new message processing logic to a given window, usually a predefined window type such as BUT- 
TON or SCROLLBAR. CallWindowProc() is called at the end of the new message processing func- 
tion to pass the message parameter data (wParam, etc.) on to the original message function for 
normal processing. 

Uses _ Frequently used to add a keyboard interface to the predefined Windows styles. You also can cus- 
tomize the functioning of default styles such as buttons and scroll bars, as shown in the example 
below. 

Returns LONG. The value depends on the message being processed. Return this value from within your 
subclassing function. _ 

See Also SetWindowLong(), GetWindowLong() 

Parameters . 

IpPrevWndFunc FARPROC: A pointer to the original message processing function for the window. You can use 
GetWindowLong() to retrieve this value. Store the value in a static or global variable, so that it is 

accessible to your subclassing function. 

hWnd HWND: The window handle for the window receiving the message. 

wMsq ’ WORD: The message (WM_PAINT, etc.). 

wParam WORD: The wParam data that accompanies the message. 

[Param ’ DWORD: The Param data that accompanies the message. 

Related Messages All messages potentially pass through this function. You can act on as many as you need, and then 
let the original window message function (called with CallWindowProc()) handle the rest. 

Comments Don’t forget to add your subclass function to the EXPORTS part of the .DEF definition file. 

Example This example subclasses a button window with a new procedure defined at the bottom of the 
listing. NewButtonProc() changes the button’s text if the button is pressed or released. After 
that, the default Windows button operations are called with CallWindowProc(). A global variable 
lnfnOldProc is used to save a pointer to the old window procedure. 

FARPROC LpfnOldProc ; /* global for old button procedure pointer */ 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : 


~ 


static HWND hButton ; 

FARPROC LpfnNewProc ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_CREATE: 

hButton = CreateWindow ("“BUTTON", "Button", 

WS_CHILD | WS_VISIBLE , 

10, 10, 100, 60, hWnd, NULL, ghInstance, NULL) ; 
ShowWindow (hButton, SW_SHOW) ; 

/* subclass the scroll bar to a new procedure */ 
LpfnNewProc = MakeProciInstance (CFARPROC) NewButtonProc, 

ghInstance) ; af 
LpfnOldProc = (FARPROC) GetWindowLong (hButton, GWL_WNDPROC) ; 
SetWindowLong (hButton, GWL_WNDPROC, (LONG) LpfnNewProc) ; 


break ; 

case WM_SETFOCUS: 
SetFocus ChButton) ; /* keep input focus on button */ 
break ; 

case WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
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}. 


MessageBox (hWnd, “press Return!", 
SetFocus (hButton) ; 
break ; 
case IDM_QUIT: /* send end oF application message */ 
DestroyWindow (hWnd) ; 
~ break ; 
3: 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 


“Message", MB_OK) ; 


default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return OL ; 


Long FAR PASCAL NewBut tonProc CHWND hWnd, WORD mess, WORD wParam, LONG lParam) 
{ a 8 


switch (mess) 


case WM_KEYDOWN: 


SetWindowText. CHENG “Pressed!") > 
break ; 


case WM_KEYUP: 


SetWindowText (hWnd, “Released!") ; 


break ; 

; ae CallWindowProc (lpfnOldProc, hWnd, mess, wParam, Param) ; 

DEFHooKPrRoc : wWin2.0 mWin38.0 mWin3l 

Purpose Provides default message processing for message hook functions. 

Syntax DWORD DefHookProc(int none, WORD wParam, DWORD lParam, FARPROC FAR * 
lplpfnNextHook); 

Description Used inside of the message hook function, installed with SetWindowsHook(). Used by Windows to 
reset the pointer to the next hook function pointed to by /plpfnNextHook. 

Uses : Hook functions are used to change Windows messages before they are sent to applications. There 
are several different types of hook functions, all of which are-explained in the section on the | 
SetWindowsHook() function. In most cases, the hook function must reside in a dynamic link 
library module (DLL). 

Returns DWORD. Returns the message being processed if nCode == HC_ACTION (which equals 0). Re- 
turns a pointer to the next hook function if »Code == HC_ LPFNNEXT (which equals —1). The 
latter is the case when UnhookWindowsHook() is called. 

See Also SetWindowsHook(), UnhookWindowsHook() _ 

Parameters 

nCode int: Specifies the action the hook function (message filter) should take. 2Code will be 0 for 

~ normal processing of messages. Code will be HC_LPFNNEXT for the last call to the hook func- 
tion, after UnhookWindowsHook() has been called. 
-wParam WORD: This is the wParam parameter of the message being processed. 
lParam DWORD: This is the /Param parameter of the message being processed. 
lplpfnNextHook FARPROC FAR *: A pointer to a memory location to hold a FARPROC data. Save this in a static 


variable. Windows will change this value on the last call to the hook procedure (when nCode = 
HC_LPFNNEXT after the program calls UnhookWindowsHook()). 
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Related Messages All Windows messages. 


Example 


This example (courtesy of Don Stegall of Playroom Software) shows a DLL that sets a keyboard. 
hook. Only WM_KEYDOWN and WM_KEYUP messages are processed by this hook function. When 
activated, the function improves the operation of the and keys. If the 
is on, and the user presses the shift key and an A-Z letter, the hook function shuts off the 
(CAPSLOcK). This imitates the way most typewriters function. See the SetWindowsHookQ functior 
description for a full code listing including definition files for use of the dynamic link library 
(DLL) hook functions. 


y* msgdil.c message filter */ 
/* Courtesy of Don Stegall —- Playroom Software */ 


#include <windows.h> 


HANDLE 
FARPROC 


hIinstanceDll ; 
LpOldHook ; 


int FAR PASCAL LibMain CHANDLE hInstance, WORD wDataSeg, WORD wHeapSize, 


{ 


} 


{ 


} 


void FAR. PASCAL SetHook CLPSTR LpsHookName, int nHookType) 


LPSTR tpszCmdLine) 

if (wHeapSize > 0) 
UnlockData (0) ; 

hins fenced ets Fraeeanee . 

return (1) ; 


/* turns on hook function */ 


FARPROC lpHook ; 


LpHook = GetProcAddress ChInstanceDLL, LpsHookName) ; 
LpOldHook = SetWindowsHook tnHook Type, LpHook) ; 


/* turns off hook function */ 


void FAR PASCAL FreeHook (LPSTR LpsHookName, int nHookType) - 


{. 


} 


sf 


FARPROC LpHook ; 


LpHook = GetProcAddress ChInstanceDLL, lUpsHookName) ; 
UnhockWindowsHook (nHookType, lpHook) ; 


/* hook function */ 


DWORD FAR PASCAL MsgKeyboardfunc Cint nCode, WORD wParam, DWORD LParam) 


char cKeys [256] ; 


if (nCode f= HC_ACTION) 


return CbefHookProc (nCode, wParam, lParam, &lLpOLdHook)) ; 


else : 
{ /* check if caps-lock, caps and A~Z at once */ 
if (wParam >= 'A' & wParam <= 'Z' & 
((GetKeyState (VK_SHIFT) & 0x80) !=0) & 
(GetKeyState CVK_CAPITAL) & 0x01) != 0) ; 
t ; 
GetKeyboardState (cKeys) ; /* 44 so, shut off caps lock */ 
cKeys CVK_CAPITALJ = cKeys CVK_CAPITAL] & OxFE ; 
‘ SetKeyboardState (cKeys) ; 
} , 7 i 
} 


return (0) ; 
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DerWinpowProc oa ee: mi Win2.0 eWin30 | mWin3l 


Purpose Provides the default processing for Windows messages. 
“Syntax — LONG DefWindowProc(HWND hWnd, WORD wMsg, WORD wParam, LONG \G Param); 


Description Programs typically only act ona fraction of the messages that Windows sends. The remainder are 
_ passed on to the default message processing logic. The default logic handles all of the more mun- 
dane tasks, such as making sure that the cursor remains visible. 


Uses Your WndProc() function should always have this function as the default message handling op- 
. oe eration. 
Returns LONG. The value depends. on the message being processed. Return this value from your 
, WndProc() function. _ 
See Also DefDigProc(). The source code for the default message processing logic is provided with the 
2 Software Development Kit in a file called DEFWND.C. It is remarkably short and worth reviewing. 
hWnd HWND: The handle to the window receiving the message. 
whsg WORD: The message (WM_SIZE, etc.). This value, and the following three, will be received by - 
your WndProc() function when a message is sent from Windows to your program. 
wParam “WORD: The wParam data passed nis ani 7 
lParam DWORD: The /Param data passed witl e message. 
_. Belated Messages All messages can be handled by thedetault message processing logic. In many cases, no action is 
oat taken. 


‘Example - This is a minimal WndProc) function: showing how messages that are not acted on by the 
program's logic default to DefWintowProa(); — 


long FAR PASCAL WndProc CHWND hWnd; one tanea desea ucns wParam, LONG lParam) 
t ’ 


pearen (iMessage) : 7* process windows messages */ 
case WM_CREATE: | 
/* etc. */ 
break ; 
Bat case WH__ DESTROY:: ’ /* stop ere */ 
. PostQuitMessage (0) ; : 7 
break ; 
default: ys default windows message preces sing */ 


return DefWindowProc (hWnd, iMessage, Marans lParam) ; 


} 
return (OL) ; 


>. 
DisrarcuMrssace Ae tomes 0. gr Win.0. wWin8.0 em Windd 
Purpose . Sends a Windows message to the window's WndProc function. 

53 Syntax LONG DispatchMessage(LPMSG IpMsq); ie . 
Description This function is used within the program's message loop. Messages are usually fetched from Win- 

: - dows with the GetMessage() function. After any needed processing (TranslateMessage() func- 
tion), the message is sent on to the program's WndProc() function for action. ~ 

Uses Used in every program’s WinMain() function message loop. | 

; Returns LONG. The value depends on the message processed, but is on ignored. 

_ SéeAlso GetMessage(), TranslateMessage() 
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lpMsg LPMSG: A pointer to a MSG structure. This is generally defined at the top of WinMain(). 
_ Related Messages All Windows messages pass through this function. 

Example This is a typical WinMain() function, including the message loop at the bottom. 

/* exanple WinMain() function / 

#inctlude . <windows.h> _ 

HANDLE ghInstance ; 


int PASCAL WinMain (HANDLE hInstance, HANDLE ubpewlnatanees LPSTR LpszCmdLine, 
int nCadShow) - 


“} 


{ a3 
HWND hwnd ; 
MSG msg; 
WNDCLASS wndclass ; 
ghInstance = hInstance 5 /* store instance handle as global var. */ 
if (thPrevinstance) 
{ 
wndclass.style = CS_HREDRAW | CS_VREDRAW ; 
wndclass. lpfnWndProc = WndProc ; 
wndclass.cbClsExtra =Q; 
wndclass.cbWndExtra =O; . 
wndclass.hInstance = hInstance ; 
wndclass.hIcon = LoadiIcon (hIinstance, gszAppNanme) : 
wndclass.hCursor = LoadCursor (NULL, IDC_ARROW) ; 
wndclass.hbrBackground = GetStockObject (WHITE_| BRUSH) ; 
wndclass.lpszMenuName = gszAppName ; 
wndclass.lpszClassName = gszAppName ; 
/* register the window class */ 
if (!RegisterClass (&wndclass)) 
‘ return FALSE ; 
‘hind = CreateWindow ( /* create the program! s window here */ 
gszAppName, /* class name */ 
gszAppName, /* window name */ 
WS —OVERLAPPEDWINDOW, /* window style */ — 
CW_USEDEFAULT, /* x position.on scree */] 
CW_USEDEFAULT,. . /* y position on screen A 
’ CW_USEDEFAULT, /* width of window */ 
CW_USEDEFAULT, /* height of window */ 
NULL, . ; _ ¢* parent window handle (null = none) */ 
NULL, /* menu handle (null = use class menu) */ 
ninstence, : /* instance handle */ 
NULL) ; /* Lpstr (null = not used) */ 
ShowWindow hwnd, ncmdShow) ; 
UpdateWindow ChWnd) ; ; 
“-. while (GetMessage (&msg, NULL, 0, 0)) /* the message loop */ 
{ ore ° 
TranslateMessage (&msg) ; 
: DispatchMessage (&msg) ; 
return msg.wParam ; 
ExrrWinpows os Win2.0 =o Win8.0) ge Win3.) 
Purpose . . ° ~ Exits the Windows anvizontaent to DOS. . 
Syntax BOOL ExitWindows(DWORD dwReserved, WORD wReturnCode); 


Deseription. _—_Starts an orderly shutdown sequence for Windows. First, the WM_QUERYENDSESSION message 
- _, is sent to all applications. If any application returns zero to this message, Windows continues to 


WINDOWS API BIBLE 


Uses 


Returns 


Parameters 
dwkeserved 


wReturnCode 


Related Messages WM 
Example 


operate. If all windows agree to exit (all return a nonzero value), a WM_ENDSESSION message is 
sent to each window. When all of the windows have stopped operations, Windows exits to DOS 
with the DOS return code specified in wReturnCode. 


Used in creating new program manager applications, as a way to exit the Windows saiaiinent 
at the end of a session. : 


BOOL. TRUE if all applications agree to quit, FALSE otherwise. 


DWORD: A reserved value. Set equal to zero. 


WORD: The DOS return code. Normal exits should return a 0 value. Can be set to 
EW_RESTARTWINDOWS under Windows versions 3.0 and above. This restarts Windows. 


_QUERYENDSESSION, WM_ENDSESSION 


If the user clicks the “Do It!” menu item, an attempt is made to exit Windows. However, as the 
WM_QUERYENDSESSION message results in the program returning 0, this window refuses to 
exit, so Windows continues to operate. If you change the return value after WM_QUERY- 
ENDSESSION to 1, and no other applications refuse to exit (such as programs that have unsaved 

data), Windows will exit to DOS. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


BOOL 


switch 
t 


| 


} 
return (OL) ; 


} 


bDExitOK ; 
CiMessage) : /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the 20e it" menu item */ 
bExitOK = ExitWindows (NULL, 0) ; 
if’ (!bExitOK) 
MessageBox ChWnd, 
: “An application retuses to Quit!”, 
"Message", MB_OK) ; 


-“ break ; 
case IDM_QUIT: /* Send end of application message */ 
\ DestroyWindow (hWnd) ; 
break ; 
} 
; break ; 
case WM .-QUERYENDSESSION: . 
return (0) ; /* refuse to quit! */ - 
case WM_DESTROY: ~ 7* stop application */ 
posveulthessege: (0) ; 
break ; 
default: : /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


' FREEPROCINSTANCE wWin2.0 wWin3d0 3 mwWin31 


Purpose | 
Syntax 
Description 


Decouples a procedure instance from a data segment. - ; 
void FreeProcInstance(FARPROC lpProc); ae 2 


MakeProcInstance() is used to bind a function to a data segment so that it can be called or 
passed as a parameter to a function external to the program (such as a Windows function). 
FreeProcInstance(). eliminates the enone . the data segment to the pee: 
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Uses. 


Returns 
’ See Also | 
Parameters 


lpProc 
Comments 


Example 
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FreeProcinstance() should be used when the need to call the function is eliminated (such as the 


end of a dialog box operation). A small amount of memory is consumed by each preedure in- 
stance, but released when FreeProcInstance() is called. 


No returned value (void). , 
MakeProcInstance() 


FARPROC: The procedure-instance address of the function to be freed. This address i is created 
by MakeProcInstance(). 


Don’t forget to add the function name to the EXPORTS part of the prograimn’s .DEF definition file 
if you are going to pass the function using MakeProcInstance(). 


This example displays a simple dialog box when the “Do It!” menu item is clicked. The dialog box 
function is at the end of the listing: The dialog box function must be passed to the DialogBox() 


function, which is external to the program (part of Windows). MakeProcInstance() is used to get. 


a procedure-instance address for the dialog box function. After the dialog box is finished, the 


' procedure-instance address is released with FreeProcInstance(). Note that the procedure-in- - 


stance address is stored in a static variable. The stack will be changed by the activities in the 
dialog box function. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : 


Static FARPROC LpfnDlgProc ; 


switch CiMessage) /*®* process windows messages */ 


} 
} 


return (OL) ; : 


_case WM_COMMAND: , /* process menu items */ 
switch (wParam) 
t 


case IDM_DOIT: /* run dialog box */ 
LpfnDlgProc = MakeProcInstance 
(DialogProc, ghInstance) ; 
DialogBox (ghInstance, “ExampleDialog", hWnd, 
LpfnDlgProc) ; 
FreeProcInstance (lpfnDlgProc) ; 
_ break ; 
case IDM_QUIT: 
DestroyWindow ChWnd) ; 


break ; 
} 
break ; 
case WM_DESTROY: . /® stop application */ 
e PostQuitMessage (0) ; 
break ; a * 
default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


BOOL FAR PASCAL DialogProc CHWND hDlg, WORD wMess, WORD wParam, LONG LParam) 
{ : . 


switch (wMess) 


+ 


_ case WM_INITDIALOG: 


return TRUE ; 
case WM_COMMAND: /* there is only one command - quits */ 
case WM_DESTROY: 

EndDialog ChDlg, 0) ; 

_Peturn TRUE ; 


return FALSE ; 
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Remember to ant the exported function name to the .DEF file: 


NAME GENERIC 
DESCRIPTION ‘generic windows program’ 
EXETYPE WINDOWS 
STUB 'WINSTUB.EXE' 
CODE. ‘-PRELOAD-MOVEABLE___. 
DATA .- * PRELOAD MOVEABLE” MULTIPLE 
HEAPSIZE 1024 
STACKSIZE 4096 
EXPORTS WndProc 
, DialogProc ~ 
GeETMESSAGE | : ~mWin2.0 gWin80 mWin3l 
Purpose Retrieves a message from Windows or gives control to another application if no messages are 
. waiting for the window currently receiving messages. 
Syntax BOOL GetMessage(LPMSG lpMsg, HWND hWnd, WORD WMsgFilterMin, WORD wMsgFilter- 
Max); 
Description GetMessage() pulls the next waiting message from Windows into the MSG structure pointed to by 
lpMsg. If no messages are waiting, control is given by Windows to another window if one has 
. waiting messages. 
Uses Used in a program’s message loop to retrieve messages. Only messages for the window are re- 


trieved. Windows programs must use either GetMessage(), PeekMessage(), or WaitMessage( to 
relinquish control from the running programs. 
Returns BOOL. TRUE if any message other than WM |_QUIT is received, FALSE for WM. “Quin. This return 
_Nalue is important because the message loop will quit looping when GetMessage() processes a 
WM_ QUIT, ending the program. 


See Also __ PeekMessage(), aes O 
Parameters 
lpMsq LPMSG: A pointer to a MSG message ‘structure. The structure is loaded with the data from the 


message. The MSG structure contains the following fields (defined in WINDOWS.H): 
typedef struct tagMSG 
{ 


HWND , hwnd; /* window handle */ - 
WORD message; /* message ID */ 
WORD wParam; _ -/* wParam value */ 
LONG lParam; /* LParam value */ 
DWORD . time; /* msec since startup */ ; 
POINT pt; /* mouse location, screen coord */, 
} MSG; ps ~ 
typedef MSG a *PMSG; 
typedef MSG NEAR *NPMSG; 
typedef MSG FAR ; *LPMSG; 
hWnd - HWND: A handle to the window receiving the messages. Set to NULL to receive all messages for 


a window and its child and popup windows (the normal case). Set to the window's handle (from 
CreateWindow()) to receive only messages for the parent window. 

wMsgFilterMin WORD: The lowest value message to Teceive. Normally set to 0. 

wMsgFilterMax WORD: The highest value message to receive. If both wMsgFilterMin and wMsgFilterMax are 

set to 0, all messages are processed. wMsgFilterMax can be set to WM _USER-1 to process only 
internally defined messages. Normally it is set to 0. 

Related Messages All Windows messages are processed. 

Notes . Anytime control is yielded to another program by itieatp: PeekMessage(), or Wait- 
Message(), local variables ee to far memory may be invalid when control is returned to 
the ‘Program. 
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Example This is a typical message loop, at the end of the WinMain() function. 
while (GetMessage (&msg, NULL, 0, 0)) 
{ 


TFanslateMessage (&msg) - 
DispatchMessage (&msg) ; 


} 

GeTMEssaGEPOs _ : mWin20 m@Win80 wWin3.! 
Purpose Retrieves the X,Y position in screen coordinates of the cursor when a medead? 4 was sent. 
Syntax DWORD GetMessagePos(void); 
Deseription Every message sent by Windows includes a point structure that contains the position of the mouse 
eee: ; - cursor when the message was sent. GetMessagePos() extracts that value, 
Uses If messages are stacking up on the message queue, the mouse may have moved since the message 

being processed was sent. Use this function to retrieve the e position where the r mouse was when a a 

eos message was sent. 

Returns DWORD. The X position is in the low-order word, and the.Y position in the high-order word. Use 


the MAKEPOINT macro to convert the DWORD value to. point structure. 
Note that the X,Y position is in screen coordinates, as are all mouse cursor soordinates Use: 
ScreenToClient() to convert to client coordinates (see example). . 


See Also ScreenToClient(), GetCursorPos() 
Parameters | None (void). . 
Related Messages WM _MOUSEMOVE 


Example After the user clicks the “Do It!” menu item, the program starts area a small line in the client 
area at the location every message is received. This provides a visual indication as to how often 
Windows sends messages. 


tong FAR PASCAL UndProc CHWND hind, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


static BOOL bTraceOn = FALSE ; ee 


HDC hoc ; 
DWORD duMesPos ; 
POINT pPoint ; 


if CbTraceOn) /* mark where the cursor was when msg. recvd */ 


hDC = GetDC ChWnd) ; 


dwMesPos = GetWessagePos () ; /* get position */ 
pPoint = MAKEPOINT (dwMesPos) ; /* convert to point struct. */ 
ScreenToClient Chiind, &pPoint) ; a /* convert to client coord. */ 


HoveTo (hDC, pPoint.x, pPoint.y) ; . - «-s /* draw a small Line there */ 
LineTo ChDC, pPoint.x + 2, pPoint.y) ; - ‘ 
ReleaseDC (hWnd, hDC) ; Bede ge 


} 
switch (iMessage) : . |* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) ; 
case IDM_DOIT: /* toggle message marking on/off */ 


if (bTrace0On) 
bTraceOn = FALSE ; 
else 
bTraceOn = TRUE ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow Chund) ; 
break ; 
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’ break ; ; 
case WM_DESTROY: /* stop application */ 
Post@uithessage (0) 5 
break ; : 
default: /* default windows message: processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
+ 
return’ (OL) ; 2 
} a 
GETMESSAGETIME | me Win2.0 wi Win3.0 sw Win3.1 
Purpose Retrieves the time value when a message was sent. 
Syntax. DWORD GetMessageTime(void); 
Description All Windows messages include a time value, which i is the number of milliseconds since Windows 
‘was started. This value “wraps around” back to 0 when the long integer value exceeds the avail- 
‘ _able bit precision. 
Uses Normally used to find out how long a message has been in the ioe queue. Compare the value 
ae -to that of GetCurrentTime(). 

Returns DWORD, the time at which the message was sent, in milliseconds since Windows started up. 
See Also °° ~~ GetCurrentTime() | 
Parameters None (void). 
Related Messages All messages are time stamped. 
Example This example displays the longest time between messages in the last 100 received. Messages are 


- received only when the mouse is in the program's client area, so moving the mouse outside for a 


few seconds will result in a long delay between messages. Also, doing nothing (no mouse move- 
ments, etc.) will result in no messages being sent to the window until an action is taken. 


long FAR PASCAL WndProc CHWND hWnd, uneigned iMessage, WORD wParam, LONG lParam). 
{ 


static, 
HDC 
DWORD 
int 
char 
static 


BOOL = bTraceOn = FALSE ; 


hDC >; 4 
dwMesTime, dwCurrentTime ; 
nElapsed ; ; 
cBuf C15] ; 7 
int - nbLargest = 0, nCount =0; 


if (bTraceOn) /* show Longest message wait in the last 100 msgs. */ 


duwMesTime = GetMessageTime () ; /* get message time value */ 
dwCurrentTime = GetCurrentTime () ; ‘/* get current time */ 
nElapsed = Cint) (dwCurrentTime - dwMesTime) ; 

if (nElapsed > nLargest) 


{ 
hDC = GetDC (hWnd) ; 
SetBkMode ChDC, OPAQUE) 3/* number eckenoutid opaque */ 
nLargest = nELapsed ; 
itoa (nElapsed, cBuf, 10) ; 
streat (cBuf, mys 
TextOut ChDC, 20, 50,. Sate strlen (cBuf)) ;/* show diff */ 
+ ; 
ReleaseDC (hWnd, hDC) ; 
if (nCountt++ > 100) /* reset counter */ 
; nLargest = nCount=0;:. 
} 
switch CiMessage) /* process Windows messages */ 
t ‘ 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 
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} 
} 
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Ct ; 
case IDM_DOIT: /* toggle message marking on/off */ 
if (bTraceOn) 
bTraceOn = FALSE ; 
else , 
t 
_ bTraceOn = TRUE ; 
hDC = GetDC ChWnd) ; 
TextOut (hDC, 10, 10, 
: "Elapsed ms. for message: 7 24) 3 
ReleaseDC ChWnd, hDC) ; 
} 
break ; 
case IDM_QUIT: /* send end of application message */. 
‘DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (Q) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


INSENDMESSAGE . BWin2.0 wmWin3.0 wWin3.l 


Purpose 
Syntax 
Description 


Uses 
Returns 
See Also 
Parameters 


Determines if the current message being processed was sent by SendMessage(). 
BOOL InSendMessage(void); 


This function distinguishes between messages that originate from normal Windows delivery of 
messages, and messages sent by other running programs. InSendMessage() will not detect mes- 
sages sent from within a program, or from a child or popup window's separate message function. 
Only messages sent from other programs result in detection. 

Handy when you have separate programs which interact. 

BOOL. TRUE if the message was sent from another application, FALSE if not. 

SendMessage(), PostMessage(), PostAppMessage(), RegisterWindowMessage() 

None (void). 


Related Messages All messages are potentially transmittable via SendMessage(). 


Example 


This example involves two programs. The first program looks for another running program with 
the title “generic” when the user clicks the “Do It!” menu item. If found, the program sends 
generic a WM_USER message. If not found, a message box warning is placed on the screen. The 
second time the “Do It!” menu item is clicked, the input focus is shifted to generic, so that it is 
active when the WM_USER message is received. . 

The second program has the title “generic.” When it receives a WM_USER message, it checks 


_ to see if the message was delivered with a SendMessage() cali and if “generic” is the currently 


active window. If these conditions are met, the window's title is changed to “Got a WM_USER 
message.” If the conditions are not met (usually because the window is inactive), a message box 
warning is placed on the screen. This example is for demonstration purposes only. See Chapter 30 
on DDE for a description of how to correctly exchange data and commands between running 
applications. Here is the WndProc() function for the message sending program. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMesSage, WORD wParam, LONG lParam) 
{ ‘ 


HWND 
char 


hWindow ; 
cBuf [£25] ; 


he Ma oe ugk Bae SS 


WINDOWS APIBIBLE = | , ste 


static’ - | BOOL ~— bFirstTry = TRUE ; 

switch CiMessage) . -. /* process windows messages */ 

{ 

case WM_COMMAND: -/* process menu items */ 

switch (wParam) tae 
{ : 
case IDM_DOIT: , /* send generic a WH_USER message */ 
hWindow = hund ; ; < /* start looking with this window */ 


while ChWindow = GetWindow (ChWindow, GU_HWNDNEXT)) 
{ 


GetWindowText ChWindow, cBuf, 24) ; 
if Cstrcmpi (cBuf, “generic”) == 0) | 
break ; /* quit {f title = generic */ 


} 
if Chwindow) 
{ /* on second try, set itis to generts w/ 
\ if ClbFirstTry) 
oa ‘ SetFocus (hWindow) ; . 
SendNessage (hWindouw, Wm USER, 0, OL) ; 
} 
else 
MessageBox (hWnd, “Did not find Generic.", 
“Message", MB_OK) ;  - 
bFirstTry = FALSE ; 
break ; 
case IDM_QUIT: 
‘DestroyWindow ChWnd) ; 


break ; 
} 
break ; - 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
7 break ; 
S default: /* default windous message processing */ 


“return DefWwindowProc Chuind, iMessage, wParam, lParam) ; 


) 
return (OL) ; 


The following listing is the ere function for GENERIC, C, the program receiving the 
message. 


. 


feng FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
€ ; 


switch (iMessage) /* process windows messages y) 
case WM_USER: 
\ aes: .. if (InSendMessage ()) 
of 
‘ =e if ChWnd != GetActiveWindow()) 
r) . : 


3 : MessageBox (hWnd, | 
: “Got message, but child not active.”, 
"Warning", MB_ICONHAND | MB_OK) ; 


u } 
else = . 
SetWindowText ChWnd, “Got a WH_USER message") ; 
} : 
break ; 
case WH_COMMAND: /* process menu items */ 
switch (wParam) 
¢ 


case IDM_DOIT: 
SetWindowText Chiind, “Parent") ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
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DestroyWindow ch¥nd>7 


Break 7 
} . 
break ; . ; ot 
case WM_DESTROY: ; : fe stopiapplicarton */ 
9 PostQuitMessage (0) ; ce i 
break ; 
default: /*' datantt windbws message processing w/ 


return DefWindowProc chins iMessage, wParam, lParam) ; 
} 
return (OL) ; 


Note that the sending function uses GENERIC’s window'title to determine which application 
is called “generic.” FindWindow() could also have been'used. Because GENERIC changes its 
window title after the first time it gets a WM_USER message and is active, the sending function 
will not be able to find “GENERIC” a second time. A better way of locating another application is ~ 
with EnumWindows(). 

This example could be improved by using the RegisterWindowMessage() function to create a 
new unique message number for both programs to exchange. WM_USER is safe only if messages 
are kept within an application and its children. . . 


MaAKEPROCINSTANCE eWin2.0 mWin30 mWin3.1 


Purpose Provides a procedure-instance address for a function. 
‘Syntax FARPROC MakeProcinstance(FARPROC /pProc, HANDLE hJnstance), 
Description If you need to call or pass a function address outside of the program, you will need to use 


MakeProcInstance() to obtain a procedure-instance handle. This binds the function to the data 
segment. Use FreeProcInstance() to decouple the function and data segment after use. Windows 
uses procedure-instance addresses so that Windows can move code and data in memory. Creating 
a procedure-instance address sets up a small section of code that resets the repens to the 
. current address of the stack and local heap when the function is called. : 
Uses Any time you need to pass a function address within Windows. The procedure-instance i is passed 


instead of the function's address. This is commonly used in passing dialog box function names, in 
enumeration functions, and in callback functions. 


Returns == ~—- FARPROC, the procedure-instance handle for the function. 

See Also ’ FreeProcInstance() 

Parameters . ; 

IpProc FARPROC: The function's real address when MakeProcInstance() is called. This is the function name. 

hInstance HANDLE: The program’s instance handle. This handle is importrant, because each instance of 
. the program will link a separate data segment to the function when MakeProcinstance() i is 

called. 

Comments Don't forget to list the function name in the EXPORTS part of the program’s .DEF definition file. 

Example See the example under the FreeProcInstance() function description. 

PEEKMESSAGE | —mWin2.0 Wind0 .8Win3l 

Purpose Checks the message queue for a message. 

Syatax BOOL PeekMessage(LPMSG lpMsg, HWND Bind oD wMsgFilterMin, WORD wMsgFiiter- 

Max, WORD wRemoveMsg); 


Description PeekMessage() is similar to GetMessage(), but more 2 passive. PeekMessage() does not wait fora - 
message to be placed in the application queue before returning. PeekMessage() yields control to 
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Uses 


other applications. Unlike GetMessage(), PeekMessage O does not wait fora no tobe paced 
in the message queue before returning. 


PeekMessage() can be used within the body of a program to do ee spore until it is 
interrupted by a message. This is commonly used in printing operations to allowg printing task to 
be interrupted by a keypress or mouse click. PeekMessage() can also be used in place of Get- 


' Message() in the program’s message loop to allow a window to execute some function continu- 


ously, but still yield control to other applications. The structure of this special type of — 


. loop should be as follows: 


white. CTRUE). 


- Returns 
See Also 
Parameters 


lpMsq 
hWnd 


wMsgFilterMin 


wMsgFilterMax 


wkemoveMsg 


if (PeekMessage (&msg, NULL, 0, 0, PM_REMOVE)) 
{ 


if (msg.message == WH. | QUIT) 


break ; 
else 
Ct) 
TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} 
} 
else 
rd Fi 
/* do some function, Like draw on client area */ 
} : 


BOOL. TRUE if a message is available, FALSE if not. 
GetMessage(), WaitMessage() 


LPMSG: A pointer to a message structure. nonncenes fills in the message data when a'mes- 
sage is found. 

HWND: A handle to the window receiving the messages. PeekMessage() will only find messages 
in the program’s message queue, not messages for other programs. If hWnd is set to —1, only 
messages posted by PostAppMessage() using a hWnd value of NULL will be retrieved. 

WORD: The lowest value message to be retrieved. You can use the WM_MOUSEFIRST and 
WM_KEYFIRST message numbers to specify the lower limit to all client area mouse messages 
and keystrokes. respectively. 

WORD: The lowest value message to be retrieved. You can use the WM_MOUSELAST and 
WM_KEYFIRST message numbers to specify the upper limit to all client area mouse messages 
and keystrokes, respectively. If both wMsgFilterMin and wMsgFilterMazx are both 0, all. mes- 
sages are retrieved. 


WORD: Specifies how the function responds to a message. The values may =n any of the ones 


_listed in Table 8-2. 


PM_NOREMOVE 
" PM_NOYIELD 
PM_REMOVE 


Messages peeked fy PeekMessagel ) are left in the scion $ message queue. 
The current application does not stop and yield to other applications. 


Messages are removed from the message queue. This value is typically used when PeekMessage() is used 
in place of GetMessage() in the program's message loop. Will not remove WM_PAINT messages, which are 
removed with BeginPaint() and EndPaint() in the message processing function. 


Table 8-2. PeekMessage() Flags. 
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PM_NOYIELD can be combined with either PM_NOREMOVE or PM_REMOVE with the C lan- 
guage binary OR operator (I). 


Related Messages All messages can be processed by PeekMessage(). 


Notes 


| Example 


Any time control is yielded to another program by GetMessage(), PeekMessage(), or Wait- 
Message(), local variables and far pointers to memory may be invalid when control is returned to 
the program. 

At the bottom of the listing is a function called NoMessages() that paints randomly colored pages 
of asterisk (*) characters on the client area. When the user clicks the “Do It!” menu item, a loop 
is entered. The loop is exited when PeekMessage() finds a client area mouse message in the 
window's message queue. If there are no messages, PeekMessage() calls NoMessages() to paint 
another astersik and then loops back to check for messages again. Note that this example has 
two message loops. The normal GetMessage() loop in WinMain() is not shown (identical to 
GENERIC.C from Chapter 1). The PeekMessage() loop operates independently from the appli- 
cation’s main message loop, allowing a separate process to go on. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG tParam) 
{ 


MSG msg ; 
switch (iMessage) 
t 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: 
while (!PeekMessage (&msg, hWnd, WM_MOUSEFIRST, 
WM_MOUSELAST, PM_NOREMOVE) ) 
{ 
NoMessages (hWnd) ; 
} 
break ; 
case IDM_QUIT: /* send end of. application message */ 
DestroyWindow (hWnd) ; 
break 7; 
} 
break ; 
case wWe_! SEStROY: 
Postaui tNessage (0) ; 
return (0) ; 
} : 
return (DefWindowProc (hWnd, iMessage, wParam, |Param)) ; 
; : 
void NoMessages (HWND hWnd) /* paint random "*" chars in client area */ 
“HDC - RDC ; 
static int “nX = 0, n¥ = 0, nRed = 255, nBlue = 0, nGreen = 0 ; 
hDC = GetDC (hWnd) ; 
SetTextColor (hoc, asp (nRed, niSteen, nBlue)) ; 
TextOut - choc, nX, nY, "*", 1) ; /* show an "*%" */ 
nX += 10 >; 
if (nX > 200) S 
{ : 
ny += 10 ; 
nX=0; . 
} ; : 
-4f Cn¥ > 200) /* alter colors when screen area is full */ 
nYy=0; 
nRed += 23-; 


Af CnRed > 255) 
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nRed = 0 ; 
inBlue -= 37 ; 
ifi(nBlue < 0) 
' nBlue = 255 ; 
} . tee 
. Released ChWnd, hdc) ; . 
2 aa _ , Ae ae 
Pescheeubess ae | | a mWin20 _mWin30 _aWin3.1 


Description — 


Uses 


Returns 
_ See Also ‘ 


_ Parameters 
hTask 


wMsg 
wParam. 


lParam 


Related Messages: All Windows 1 messag may be passed with this function. 


Note 


/* generic.c 
/e 8] 


- Putsa Message i the application’ Ss message queue. 
BOOL PostAppMes (HANDLE h7ask, WORD wMsqg, WORD ene LONG eanen 


-PostAppMessage() is similar to PostMessage() except that the message is sent to a task instead 
\ of a window. A task is. a running application (not a DLL). 


Used for communication between aieereut tasks. This function is used less frequently t than 
. PostMessage(). Ms a \ 


BOOL. "TRUE if the message was posted, FALSE on error. - 
Senden) PostMessage(), ania ea \ 


HANDLE: A handle to the current task. Use GetCurrentTask() and EnumTaskWindows() to fetch — 


_ task handles. _ “< 
. WORD: The mesgage | to send (such‘as WM_MOVE). 


" WORD: The wParam value to be passed with the message. See Chapter 9 , Windows Messages, for 
ges and their parameter values, 


DWORD: The IPa cam value to be passed with the message. . 


‘NULL if the meSgage was Sent using PostAppMessage 6 See ' 


in this case, «When he user licks the “Do It!” menu item, a WM_USER message is sent. to the 
application’ 3 message queue. PeekMessage() is used in the message loop to pull in the message. 
If the detected message is found to be equal to WM_USER, the function StarMessages() listed at 
the bottom i 3 called‘to paint an astersik on the window’ 8 client area. This is certainly a round- 
about method of painting on the screen: The example was designed to illustrate how messages 
can be generated from within an application and end up being acted upon via the message loop. 


The message Ser GetMessage() « or. PeekMessage() will havea 1 hurd parameter’ value of 


example of creating a child window with message processing oe 


‘Rinclude eutadoes. h> 
#include “generic. h". 


int sien oe CHANDLE benet tices HANDLE SEREM ENS ERES LPSTR isscteditac, 


int nRCmdShow) 

{ = 

. HWND hWnd ; ) 

_MSG msg ; _ 
~WNDCLASS wndclass ; 
ghInstanc ‘= hInstance rm .* /* store instarice handte as global var. */ ° 
if (!hPreyInstance) /* Load data into window class struct. */\ 
C ae 


\ 


wndclass.style CS_HREDRAW | CS_ VREDRAW ; | 


wndclass. LpfnWndProc = WndProc ; es 
wndclass.cbClsExtra = 0°;- ; 
=0 ee 


wndclass.cbWndExtra ~ 
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wndclass.hInstance 
wndclass.hicon 
wndclass.hCursor 
undclass.hbrBackground 
undclass.tpszMenuName 
wndclass.lpszClassName 


noun 


/* 


ee 
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hInstance ; 

Loadicon ChInstance, gszAppName) ; . 
LoadCursor (NULL, IDC_ARROW) ; ; ao 
GetStockObject CWHITE_BRUSH) ; ie 
gszAppName ; 
gszAppName ; 


register the window class */ 


if C!RegisterClass (&wndclass)) 


return FALSE ; 
} 
hWnd = CreateWindow ¢ 
gszAppName, 
gszAppName, 
WS_OVERLAPPEDWINDOW, 
CW_USEDEFAULT, 
CW_USEDEFAULT, 
CW_USEDEFAULT, 
CW_USEPEFAULT, 
NULL, 
NULL, 
hIinstance, 
NULL) -; 
_ ShowWindow (hWnd, nCadShow? : 
UpdateWindow (hWnd) ; 
while (TRUE) 


J 
/* 


create the program's window here */ 
class name */ 

window name */ 

window style */ 

x position on screen */ 

y position on screen */ 
width of window */ 

height of window */ 

parent window'’handle (null 
menu handle (null = 
instance handle */ 
lpstr (null = not used) */. 


= none) a] 
use class menu) */ 


/* the program's message loop */ 


{ : 
if (PeekMessage (&8msg, NULL, 0, 0, PM_REMOVE)) 
{ 
if (msg.message == WM_QUIT) 
break ; 
else if (msg.message == WM_USER) 
StarMessages (hWnd) ; 
else 
_f a 
~ TranslateMessage. (&msg) ; 
* ‘ DispatchMessage (&msg) ; 
s } ‘ 
} 
} 


return msg.wParam ; 


lang FAR PASCAL WndProc CHUND hlnd,. unsigned iNessage, WORD wParam, LONG pep rants 
{ ‘ 


switch CiMessage) 
{ 


case wr COMMAND: 


switch (wParam) 


{ 
case IDM_| DOIT: 


/* process menu items: */ 


/* send a WM_USER message */ 


tay 


‘PostAppMessage, 
(GetCurrentTask(), WM_USER, 0, OL) ; 


, 
break ; 
case IDM: | QUIT: 


DestroyWindow Chwnd) ; 


break ; 
SF re } : 
break ; 


\ 
case wh DESTROY: 


PostQui ttessage (QO) ; 


eeturn (0) ; 


e 


void StarMessages (HWND hWnd) 
t 


/* paint "*" characters in client 


a 5 ec, 


return (DefWindowProc Chiind, iMessage, wParam, LParam)) ; 


area ef 
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HDC 


static 


hDC ; ; 
int nX = 0, nY = 0, nRed = 255, nBlue = 0, nGreen.= 0 ; 


hoc = GetDCc ChWnd) ; 
SetTextColor ChDC, RGB (nRed, eee sey nBlue)) ; 


TextOut ChDC, nX, nY, "*",  ; /* ahoe an "x" &/ ‘ 
nX += 10 ; . 4 
oe (nx > 200) 
ny += 10 ; 
nX.=0; 
} : . 
vi Cny > 200) /* alter colors when screen area is full */ 
ny = 0; | 
nRed a 23; 
if (nRed > 255)... & 
nRed =0; | : ° 
nBlue -= 37 ; 
if (nBlue < 0) 
. nBlue = 255 ; 
: ; 
ReleaseDC ChWnd, rvs) = 
; 
PostMEssAGE Win2.0 wWin3.0 gmWin3.1 
Purpose Puts a message on a window's message queue. 
Syntax BOOL PostMessage(HWND hWnd, WORD wMsg, WORD wParam, LONG /Param); 
Description PostMessage() places a message on a window's message queue and then returns. The posted 
message can be recovered by using either GetMessage() or PeekMessage() in the program's mes- 
sage loop. PostMessage() returns immediately, without waiting for the message to be processed. 
PostMessage() cannot be used to send a message to a control (such as a button or list box) where 
a returned value is expected. 
Uses PostMessage() can be used in place of goto: commands to cause another section of the program’s 
logic to be executed, but only after the current message has been processed. The function has the 
ability to send a message to all running programs at one time. 
Returns BOOL. TRUE if the message was posted, FALSE on error. 
See Also SendMessage(), PostAppMessage(j 
Parameters | . 
hWnd HWND: A handle to the window receiving the posted message. If set to OxFFFF (—1), all top-level 
windows will receive this message. Child and popup windows do not receive the message. 
wMsg WORD: The message to send (like WM_MOVE). : 
wParam WORD: The wParam value to be passed with the message. See Chapter 9, Windows Messages, for 
a full list of ‘Messages and their parameter values. 
lParam DWORD! The lParam value to be passed with the message. 
Related Messages All Windows messages can be posted with this function. 
Example When the user clicks the “Do It!” menu. item, the program posts a WM_USER message to all 


applications. The window’s message function (WndProc()) responds to WM_USER messages by 


’ printing a message on the client area. If more than one instance of this program is run, all of them 


will print the message if any one of the instances posts the WM_USER message. This example 
could be improved by using RegisterWindowMessage() to create a new, unique message. 
WM _ USER is safe only if messages are confined to within one application program and its 
children. 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam? 
{ : . 
HDC hoc ; 


switch (CiMessage) -‘/* process windows mes: -es */ 
£ 
case WM_USER: 
hDC = GetDC (hWnd) ; 
TextOut (hOC, 10, 10, “Got WM_USER message.", 20) ; 
ReleaseDC ChWnd, hDC) ; 
_ break ; 
’ case WM_COMMAND: /* process menu items */ 
switch (wParam) : 
{ 


case IDM_DOIT: - /* send popup window a fake keypress */ 
PostMessage (OxFFFF, WM_USER, 0, OL) ; 
break ; 
case IDM_QUIT: /* send end of application message */. 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; . 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; ; , 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} . , 
return OL ; 
} 
PosTQuITMESSAGE mWin2.0 wWin30 mWin3.l 
Purpose Terminates an application. 
Syntax void PostQuitMessage(int nExitCode); 
Description PostQuitMessage() posts a WM_QUIT message to the appliccton. The program’s message loop . 
: _ . Should be constructed so that when this message is received, the program exits. 
Uses - Normally used to process WM_DESTROY messages and menu items that force exiting hed pro- 


_ gram. Use DestroyWindow() elsewhere in the application to start the application shutdown process. 
Returns - No returned value (void). 


See Also PostMessage(). PostQuitMessage() is functionally equivalent to aia (hWnd, WM _QUIT, 
ee sa : 


Parameters 

nExitCode int: This code will be passed as the wParam araniekes when the WM _ QUIT message is pulled off 
the message queue. — , 

Related Messages WM_DESTROY, WM_QUIT Pas 

Example This WndProc() example shows the typical Sioeaane of DestroyWindow() and PostQuit- 


Message(). The DestroyWindow() is in response to the user clicking the “Quit” menu item. Win- 
dows responds by sending a WM_DESTROY message. This is also sent in response-to the user 
double-clicking the system message button (at the upper left corner of the application window), > 
or clicking the system message button and then selecting “Close” from the system menu. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iNessage, WORD wParam, LONG lParam) 
{ 


switen Cimessage) ys process windows messages */ 
{ 
case WM_COMMAND: .-— ....., /* process menu items ay 
switch (wParam) : 
{ 
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7. Case IDM_ DOIT: Bean -/* send popup window a fake keypress */ 


“/* some action done here */ 
break ; ; 
case IDM QUIT: - /* send end of application message wy, 
DestroyWindow ChwWnd); 
break ; 
} 
break ; ; .e 
case WM__ DESTROY: ca oawty. : /* stop application */ 
PostQuitMessage (0) ; . 
break > 
default: - ; /* default windows message processing x] 
= , return DefWindowProc (hWnd, iMessage, wParam, tParam) ; 
} fg 
. * peturn (COL) ; . 
} : Sis tht 
; Recistue WinnowMessior Dre mgs m@Win2.0 m@Win3.0 mWin3.] 
Purpose Creates a new, unique Windows message number 
Syntax. WORD RegisterWindowMessage(LPSTR IpString); 
Description "When two separate programs communicate by sending and receiving messages, it is not safe to - 
use the normal WM_USER, WM_USER + 1, etc. message numbers for special messages. This is 
because another, unrelated application might use the same message for a different purpose. : 
Uses - Communication between different applications. ~ 
Returns WORD, the new message value. It will be between 0xC000 and OxF FFF. Returns NULL on error. — 
See Also. SendMessage(), PostMessage(), FindWindow() 
Parameters oS, Cieen aa ea, at pak o4.% 7 | 
lpString LPSTR: A pointer to the string name to be registered. If the same string name is used by two 


; different applications calling RegisterWindowMessage(), the same message aes will be re- 
oi os os: + turned-for both applications, : 


Example ” This example shows two program WndProc() functions. The first is a message sender, A ae 
fo ope message.is created using RegisterWindowMessage() when the program is started. If the user 
_:.’. Clicks the “Do It! menu item, the program gets a handle to the program called “GENERIC” and 
sends it the unique message. The second time “Do It!” is clicked, “GENERIC” is made the active 
window before the unique message is sent by calling SetFocus(). See Chapter 30, Dynamic Data 

‘Exchange, on DDE, for better ways to exchange data between applications. 


long FAR PASEAL WndProc CHWND hwnd, unsigned -iMessage, WORD wParam, LONG lParam) 
t a ; 


SOHWND Se ST Se Window pie 
static BOOL bFirstTry = TRUE ; 
static WORD. wNewMessage = WM_NULL ; 
| switch Cimessage) . fe. eh tae a .,/* process windows messages */ 


: Case: WM CREATE: sty ea 


fo ine or ; WHE MHERSEQE:= RegisterWindowMessage ("NEWONE") ; 

gar! 4 ae eee ‘break ; ae lar t 

as J Vease’ WM _-COMMAND =" ‘+ -7* process menu items */ 
in ees. gwiteh (wParam) | sa 
ie { os 
con oy, “case 1DM_ DOIT: /* send generic a new message mM 

pe OF hWindow = FindWindow Svgenenie: y ~generie') ; 
if ChWindow) : Toes 
{ Ete a 


if (!bFirstTry) /* on second try, set-focus to */ 
SetFocus (hWindow) ;/* generic, so awake*/ 
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SendMessage (hWindow, wNewMessage, 0, OL) ; 
} : ; 
else 
MessageBox (hWnd, “Did not find Generic.", 
“Message”, MB_OK) ; 
bFirstTry = FALSE ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; : 
case WM_DESTROY: /*® stop application */ 
PostQuitMessage. (0) ; 
break ; 
default: /* default windows message processing */ 


return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 
} 


return COL) ; 


The listing below shows the WndProc() function for the second program. This program-re- . 

“~ eeives a message sent by the program shown on the previous listing. On startup (WM_CREATE), 
the same unique message is created in this application. The message number will correspond to 
the number retrieved from RegisterWindowMessage() in the sending program (above) as both 
calls to RegisterWindowMessage() use the same string constant “NEWONE.” If the window re- 
ceives the unique message, a response is generated. If the window is active when it gets the 
message, the window’s title is changed to “Got a unique message.” Otherwise, the window is not 
active, and a message box i is generated. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ - 

static WORD wNewMessage = WM_NULL ; 

if (iMessage == wNewMessage) 

{ 


ReplyMessage (NULL) ; | ee 


if ChWnd != GetActivewindow() 
£ 


MessageBox Chund, "Got message, but child not active.", 
cnernang’? MB_ ICONHAND | MB =0K) 5 


} 
else ae 
SetWindowText ChWnd, Pedew untaus message") ; 
switch (iMessage) Ss '/* process windows messages */ 


t 
; case WM_CREATE: 
wNewMessage = RegisterWindowMessage C"NEWONE") ; 


break ; ; 
case WM_COMMAND: '  7* process menu items */ 
switch (wParam) Pe 
a ; , : s Zhe , 
case IDM_DOIT: arr 
SetWindowText Chuind, “Parent") : 
break ; 


case IDM_QUIT: _ . . & ayy Sh gas 
Destroy eEndow Chwind). ; Je 
break ; ; ao ee aoe 


} : ’ 7 ean: 
break ; a) Po Bea 
case WM_DESTROY: /* stop application */ 
4 PostQuitMessage (0) ; 


break ; 
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} : 
return (OL) ge or! 


. default: = +). ‘e+ «4% default:windows message processing oe 


return DefWindowProc ChWnd, aNPSSeue? wParam, lParam) ; 


} Frey ie 
REPLYMESSAGE mg Win2.0 om Win3.0) sm Win3.t 
Purpose Frees the application sending a message to continue to execute. . 
' Syntax void ReplyMessage(LONG /Reply); 
Descriptior This function is used to respond to messages sent from another window or application calling 
SendMessage(). The /Reply value ultimately becomes the returned value from SendMessage() in 
_the sending application. It is not necessary (or bees) to as with ReplyMessage() if the 
Ag "message was posted with PostMessage(). 
~ Uses ' Used to return a value to another window which sent the messa‘e. Returns control to the sending 
window. 
Returns... No returned value (void). ; © : 
‘See Also 60 SendMessage() , Beg WindoeMesaee) 2 
; Parameters, : “ 
Reply. “LONG: ‘the return value for the message sent. The application which sent the message will re- 


‘ceive this value as the returned value from SendMessage ().. 


Related Messages User defined ‘Messages, created with RegisterWindowMessage(). 


Note 


Example 


In situations where an application receiving a message calls a dialog box or message box, the 
_ System can become. frozen while both the sending and receiving applications wait for action. 
*ReplyMessage() frees the sending application to continue execution, even if the receiving appli- 
cation has not completed processing the message: © ( ~' a 


The example illustrated in Figure 8-3 shows the WndProc() functions for both a message sending 
application, and a message receiving aaa Both applications obtain the same unique mes- 
sage number by calling eS, : 

RegisterWindowMess- —a.eeaop 


Rep Ae ge 
age(). The fist sending [pow aun | [pow ae 
Sender got 77 back. Receiver got message, wParam = 11, [Param = 22 


application transmits this 
message to the applica-. tL 

tion titled “GENERIC” us- | Figure 8-3. ReplyMessage() Example. 

ing SendMessage(). The 

message is sent with the wParam value set to 11, and the lParam value set to 22. When the 
second (GENERIC) application receives the message, it replies with a value of 77. The receiving 
_ application displays the [Param and'wParam values it obtained from the message, while the 
sending application displays the reply value. ; 


© WndProc() Function for the Sending Application (SENDER. ion 
_ long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
ae 


static ; WORD wNewMessage ; 
© HWND hWindow ; 
int. nReturned ; ick 
HDC hDC ; 5 BEA 
char — cBuf. C128] ; 
switch (iMessage) re ne /* process windows messages */ 
{ 2 ae 


case WMH_CREATE: 
RN ENMCe ane = RegisterWindowMessage ("NEWONE") ; 
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, break; 
case WM_ COMMAND: . /*- process menu items */ 
switch (wParam) so, i 
case IDM_DOIT:- - : '. 7* User hit-the "Do it" menu item */ 
_ hWindow = FindWindow (“generic” » "generic”) ; . 
' 4f ChWindow): 
{ 


‘ 


nReturned = SendMessage ChWindow, | 

wNewMessage, 1, 22k) ; : 

hDC = GetDC ChWnd) ; 

TextOut (hdc, 0, 0, cBuf, usprintf (cBuf, 
“Sender got %d back. pea nReturned)) ; 
ReleaseDC (hWnd, hDC) ; of 

} 

break ; 
case IDM QUIT: /* send end of application message */ 
pore Oy mngow ChWnd) .; 
break ; = 
+ 
break ; . 
case WM_DESTROY: /* stop application */ _. : 
PostQuitMessage (0) ; 
ed break ; NAYS 
default: -/* default windows message processing x] 
return DefWindowProc ChWnd, iMessage, wParam, (Param) ; 

}.: Fi : 

return (OL) ; 

} 


> WndProc() Function for the Receiving Application (GENERIC.C) 
ies FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


static WORD unewnesseae = WMLNULL ; 


HDC. - hdc ; Sok Be Sule 3 
char e cBuf. £128]; . ee ee et ee a 
if (iMessage == igNe@umessaue) | | 

{ . 


ReplyMessage tee et 
- hDC = GetDC: ChWnd) ; 
TextOut ChdC, 0, O; outs deprine® (eBuf, 
"Receiver got message, wre tae = Zu, (Param = Zlu", 
wParam, lParam)) ; ae 
Rereanene ChWnd, hDdC) ; 


} ‘ faa, 
switch (iMessage) " /* process windows messages */ 
{ es “8 ae 
case WM _CREATE: 
’ wNewMessage = RegisterwindowMessage C"NEWONE") ; 
' ; break; © 
case WM_COMMAND: /* process menu items */ ot 
switch (wParam) 
case IDM_QUIT: 
DestroyWindow SAWN? 
peesk:7 : 
} 
break ; 
case WM_DESTROY: ; /* stop application */ 
porous snrenase (0). ; 
; break ; . og {oP MES. 
default: /* default windows message processing */ 
a ee: return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} * . ae: ane 


return COL) ; 
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Figure 8-4, SendMessage() 


pain 


SENDMESSAGE | 
Purpose Sends a Windows message directly to a window's message function. 
Syntax —_- DWORD SendMessage(HWND hWnd, WORD wMsg, WORD wParam, LONG |Param); 
Description Can be used to send any window a. message. The message is acted on camveniately, as it Rypasses 
eas the receiving window's message queue. 
Uses Used most often to communicate with control windows, such a as 
buttons and list boxes. Used in cases where a program has a 
series of child windows that each have separate message pro- 
cessing functions. Any window can send any other window a 
message. The sending window does not restart processing until 
the message is processed by the receiving window. Reply- 
Message() is used to return control and a value back to the 
sender. SendMessage() can also be used within one window to — 
'_ reduce duplicate code. SendMessage() provides an alternative 
to goto: statements in message-based programming. 
Returns DWORD. Normally the returned value is not used. The returned 
value depends on which of the Windows messages was sent. 
See Also ReplyMessage(), Puasa); SendDlgltemMessage(), Register WindowMessage(), InSend- 
Message()} 
Parameters 
hWnd — HWND: The handle of the window to receive the message. Set to OxFFFF CY) to pass a message 
‘to all parent and popup windows (not child windows). 
wMsg WORD: The message to be sent (such as WM_PAINT). . 
wParam WORD: The wParam data to be sent with the message. See Chapter 9, Windows Messages, for a 
full list of the Windows messages and the related wParam and [Param values. 
[Param DWORD: The /Param data to be sent with the message. . 


Related Messages All Windows messages can be sent using this function. A useful trick here is to create special 
messages, specific to your program. Windows defines WM_USER as the lowest message value that 
you can safely use. You can define your own custom messages as WM_USER + 1, WM_USER + 2, 
etc. This is an elegant way to allow separate message functions for child and popup windows to 


Example 


communicate. 


See the previous example under ReplyMessage() for an example of communication between two 
applications. In this example, the parent window creates a child popup window. The parent sends 
the child window 2a WM_USER message when the user clicks the “Do It!” menu item. The 
WM_USER message has the parent’s window handle set as wParam, so that the popup window 


can print out the parent’s name. 


tong FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD uParan, LONG lParam) 
C+ 


HBC 


hDC ; 


static WNDCLASS wndclass ; 
static HWND hPopup, hParent ; 


switch (iMessage) 
r¢ . 


' ¢* process windows messages */ 


case WM_CREATE: ; /* build the child window when program starts */ 


wndclass.style ee 
“wndclass.lpfnwWndProc = ChildProc ; 
wndclass.cbClsExtra — =O; 
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wndclass.cbWndExtra 0; 
wndclass.hInstance ahinstance; 
wndclass.hIcon NULL ; 


wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.lpszClassName 


Loadcursor CNULL, IDC ARROW) ; 
GetStockobject CERGHAY- " BRUSH) ; 
NULL ; 
“SecondClass” = 

/* register the window class */ 
if(RegisterClass (&wndclass)) 
{ 


- 


hPopup = CreateWindow ("SecondClass", “Popup Window", 
WS_POPUP | WS_VISIBLE | WS_BORDER | WS_CAPTION, 
10, 50, 200, 150, hWnd, NULL, ghinstance, NULL) ; 
ShowWindow (hPopup, SW_SHOW) ; 
} 
break ; 
case WM_COMMAND: /* process menu items */ - 
switch (wParam) : 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */: 
hParent = GetParent (hPopup) ; 
/* Tell popup window its parentage */ 
SendMessage ChPopup, WM_USER, hParent, OL) ; 
break ; 


case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; : 
break ; 

3 

break ; 


case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 


default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 


return (OL) ; 


/* Here is a separate message processing procedure for the child window */ 


Long FAR PASCAL ChildProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ‘ 


HDC hoc; 

HWND hParent ; 

char cBuf £25] ; 

switch (CiMessage) /* process windows messages */ 
{ . 


case WM_USER: /* message from parent ~ wParam is parent handle */ 
hDC = GetDC (hWnd) ; 
TextOut (hDC, 1,1, “My Parent. window is:", ak 
GetWindowText (CHWND) wParam, cBuf, 24) ; 
2B TextOut (hDdC, 1, 15, eBUT strlen (cBuf)) ; 
eT ReleaseDC (hind, hDC) ; 


break ; ; 
case WH_| DESTROY: _/* stop the application */. 
Postaui thessage (0) ; ” ; 
- ; break ; 
default: /* default wandeus message processing ee 


return DefWindowProc snlnge Messages. wParam,” (Param) ; 
} ; 


return (OL) ; 
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SETMESSAGEQUEUE ? oe : me Win2.0 mm Win3.0 mWin3.1 
Parpose Changes the size of an application’ S Message queue. - = 
Syntax . BOOL SetMessageQueue(int nMsg); a ; 

: Description Windows defaults to a message queue size of eight messages. This is adequate for most applica- 


tions, but it may be too small for an application that needs to track a series of mouse movements, 
or other repetitive activities involving messages. — 


Uses Used in the program’s WinMain() function to set the message queue size before any windows are 
oe -_ created and before any messages are sent. 

Returns BOOL. TRUE if the message queue size was Heh FALSE if not. If FALSE is returned, the program 

should try setting the queue size again with a smaller mee value. Otherwise ,the program will 

‘ not have a message queue. 

Parameters 

nMsg m int: The new queue size. This is the maximum number of messages the application’s queue can 
contain. 


Related Messages Most messages go through the application’ 5 message queue. Exvepons are messages transmit- 
—_ ted with SendMessage() and UpdateWindow().. 


Example This is an example WinMain() function that sets the message queue size for the application equal 
to 256 messages (a very large value). If this proves too large for the available memory space, 
SetMessageQueue() is continually tried with message queue sizes s repeatedly divided by 2 (right 

shift by one digit i is the same as division by two). 


int PASCAL WinMain CHANDLE hinstance, HANDLE hPreviInstance, LPSTR LpszCmdLine, | 
int nCmdShow) 


{ 2 + 
HWND hWnd ; : /* a handle to a message */ 
MSG msg ; Pes /* a message */ 
WNDCLASS wndclass ; ed /* the window class */ 
int nMsgNumber ; /* message queue size */ 
ghInstance sd hInstance ; . /* store instance handle as global var. */ 
nMsgNumber = 512 ; /* twice desired # messages in queue size*/ 
do , 
C a 
; nMsgNumber >>= 1; /* divided by 2 */ 
dwhile Scene rearnuede amsgNumber)) ay 
[Other program lines] : 
SeETWinvowsHook ~ 2 es Win 2.0 wm Win 3.0 wWin3.1 
‘Purpose Installs a Windows message filter function. . aan 
Syntax _  FARPROC SetWindowsHook(int nFilterType, FARPROC IpFitterFune); 
Description There are several different types of filter functions, specified with the nFilterType parameter. 


Multiple filters can be installed at the same time, forming a chain of message processing func- 
| tions. In all but one filter type, the filtering function must reside in a dynamic link library (DLL). 
Uses Hook functions can monitor, act on, or change Windows’ messages before they are sent to appli- 
cation programs. Hook functions can be used to customize Windows’ behavior on a system-wide 
basis. For example, keyboard messages can be remapped for all WM_KEYDOWN and WM_KEYUP 

messages to specify an alternate keyboard layout when the hook function is set. 
Returns FARPROC, the procedure-instance address of the previously installed filter function. NULL if this 
is the first filter installed. The calling program should save this value in a static variable. ae 
value is passed to the PetloortracO amen as the fourth argument. 
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‘See Also. | 
Parameters 


nFilterType 
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UnhookWindowsHook(), DefHookProc(). 


int: Specifies the type of filtering function and what type of messages will be.diverted to the filter 
before being sent to an application. The choices are listed in Table 8-8. 


WH -CALLWNDOPROO . Filter processes Sah messages sent a Sense) The hook function rit beina DLL. 


WH_GETMESSAGE 


Primarily for debugging purposes. 


Filter processes messages immediately after the GetMessage() or PeekMessage() function is 
Called in a program’s message loop. All messages are ais to the filter. The hook function > 
must be ina DLL. , 


WH_JOURNALPLAYBACK Used with WH_JOURNALRECORD. The filter function = back an event message recorded 


with WH_JOURNALRECORD when an event is requested by the system messe0e queue. The 
hook function must be in a DLL. 


WH_JOURNALRECORD Used with WH_JOURNALPLAYBACK. The filter function records al messages processed in the 


system message queue. The stored messages can be played back by a WH | JOURNAL- 
PLAYBACK hook. The hook function must be in a DLL. 


WH_KEYBOARD Filter processes WM_ KEYDOWN and WM |_KEYUP messages received by GetMessage() or 
PeekMessage(). The hook function must be in a DLL. 
WH_MSGFILTER Filter processes messages for an application's menu, message boxes, and dialog boxes. This is. - 
~ the only application-specific hook. The hook function does not have to be in a DLL, and can it 
oO . & be part of the program. . 
WH_SYSMSGFILTER Filter processes messages for all menus, message boxes, and dialog boxes. Similar to 
WH |_ MSGFILTER, but applies system-wide. The hook function must be in a DLL. 
Table 8-3. Hook Function Types. 
lpFilter Func . FARPROC: The procedure-instance address of the filter function. 
Related Messages All messages processed by the hook function. 
Hook Function 
Each type of message hook expects a different kind of filter function. Each of the function types 


Prototypes 


is described below. With the exception of WH_MSGFILTER, all filter functions must be in dy- 
namic link libraries (DLLs). The filter function can have any name. “FilterFunc” is shown in the © 
examples, The calling program must use MakeProcinstance() to get the procedure-instance ad- 
dress of the function before it is passed to SetWindowsHook(). The hook function must also be 
referenced in ie EXPORTS section of the aie s ‘DEF definition file. 


WH. —CALLWNDPROC 


nCode 


wParam 
lParam 


void FAR PASCAL FilterFunc(int node, WORD w wPliram, DWORD lParam) ; : 


int: A code that the filter function should examine before processing a message. IfnCode is less 
than zero, the function should pass the message to DefHookProc() without further actions. 


WORD: TRUE (nonzero) if the message was sent by the current task. FALSE if not. 


DWORD: A pointer to five WORDs of data containing the following information. (The data struc- 
ture is not defined in WINDOWS.H, so no default names are available for references. You can use 
the names provided in parentheses for a consistent set of structure item names if you want to 
create your own structure. 
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Returns 


WORDI (hlParam) - The high-order word of the [Param message received by the filter function. 
WORD2 (liParam) - The low-order word of the [Param message received by the filter function. : 
WORD3 (wParam) - - The wParam parameter passed with the message. 
WORD4 (wMsq) - - The message received by the filter. 

WORD5 (hWnd) - The window handle of the window that will receive the message. 


_ This filter processes only messages sent by SendMessage(). 


No returned value (void). This type of filter processes only messages sent by SendMessage(). The 
hook function must be in a DLL. 


WH_ GETMESSAGE 


nCode 


wParam 
lParam 
Returns 


void FAR PASCAL FilterFune(int nCode, WORD wParam, DWORD lParam) ; 

int: A code that the filter function should examine before processing a message. If Code is less 
than zero, the function should pass the message to DefHookProc() without further actions. 
WORD: Always NULL. . 

DWORD: A pointer toa message structure. 

No returned value (void). This filter processes messages immediately after the GetMessage() 


function is called in a program’s message loop. All messages are passed to the filter. The message 
is returned to GetMessage() after any changes made by the hook function. 


WH_JOURNALPLAYBACK 


nCode 


wParam 


lParam _ 


Returns 


DWORD FAR PASCAL FilterFune(int nCode, WORD wParam, DWORD lParam) ; | 


int: A code that the filter function should examine before processing a message. If nCode is less 
than zero, the function should pass the message to DefHookProc() without further actions. If 
nCode equals HC_SKIP, the function ehoules wait until the next val to return its next recorded 


~ message data. 


WORD: Always NULL. 


DWORD: A pointer to a message structure. This function copies the event data saved by the 
WH_JOURNALRECORD message filter back to the location pointed to by the Param parameter. 
The data should not be modified. The function should return the amount of time (in clock ticks) 
that Windows should wait before processing the message. Return OL for immediate processing. 


’ The amount of time (in clock ticks) the system should wait before processing the message. This 


type of hook is used with WH_JOURNALRECORD. The filter function plays back an event mes- _ 
sage recorded with WH_JOURNALRECORD when an event is requested by the system message 
queue. The hook fume must be in a DLL. 


WH _ JOURNALRECORD | 


- nCode 


wParam 
lParam 


| Returns 


void FAR PASCAL FilterFune(int nCode, WORD wParam, DWORD Param): ; 
int: A code that the filter function should examine before processing a message. If nCode is less 


than zero, the function should pass the message to DefHookProc() without further actions 
_ WORD: Always NULL. se 


DWORD: A pointer to a message structure. If nCode i is greater or equal to zero, the filter function 
should save a copy of the message data pointed to by /Param. This message will then be sent on 


- to the program’s message function (after the Specified delay) wen the WM_JOURNAL- 
- PLAYBACK filter function i is called. 


No returned value (void). This filter type i is used to record messages, for future playback by a 
WM_JOURNALPLAYBACK hook. This type of hook is used with WH_JOURNALPLAYBACK. The - 


250 


WH_KEYBOARD 
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filter function records all messages processed in the system message queue. The stored messages 
can be played back by a WH_J OURNALPLAYBACK hook. The hook function must be in a DLL. 
DWORD FAR PASCAL FilterFune(int nCode, WORD wParam, DWORD lParam) ; 


int: A code that the filter function should examine before processing a message. IfnCode is less 
than zero, the function should pass the message to DefHookProc() without further actions. If the 
value is HC_NOREMOVE, the application used PeekMessage() with the PM_NOREMOVE option. 


_ The message will not be pulled from the system message queue. 


wParam 
- (Param 


Returns 


Comments 


WH_MSGFILTER 
nCode 


WORD: The virtual key code exactly like wParam in WM_KEYDOWN and WM_KEYUP messages. 


DWORD: The key scan code, repeat count, etc. Exactly like [Param in WM_KEYDOWN and 
WM_KEYUP messages. The filter processes only WM_KEYDOWN and WM_KEYUP messages re-. 
ceived by either GetMessage() or PeekMessage(). The function should return 0 if Windows is to 
process the message, 1 if the message should be discarded. This can be a rapid way of removing 
specified keyboard messages. 


Should return the value rowined by DefHookProc() if nCode == HC_LPFNNEXT (== -1). Other- 
wise return NULL. 


An example of a keyboard hook function is shown in the example code under DefHookProc() in 
this chapter. Although the wParam and [Param values received by this type of hook match those 
received by your program on a WM_KEYDOWN or WM_KEYUP message, changing wParam or 
lParam within the hook function will not Affect the values passed to the main program’s message 
loop and message processing function. To modify these parameters within the hook function, use 
the WH_GETMESSAGE type of hook, and change the wParam. and lParam values within the msg 
structure pointed to by the hook function's /Param value. The changes within the hook will hap- 
pen before the message is sent to the program’s message processing function. 


int FAR PASCAL FilterFunc(int nCode, WORD wParam, DWORD atin ; 
int: Must be one of the values listed in Table 8-4. 


Pee EG Weaning 


MSGF_DIALOGBOX 


The eRe cag ee is froma a dialog t box. Jo 


MSGF_MESSAGEBOX The message being processed is from a message box. 

MSGF_MENU The message being processed is mouse or keyboard input from a menu. 
MSGF_MOVE A MOVE message is being processed. 

MSGF_SIZE A SIZE message is being processed. 


MSGF_SCROLLBAR 


A SCROLLBAR message is being processed. 


MSGF_NEXTWINDOW A window is gaining the input focus. 
Table 8-4, WH_MSGFILTER nCode Values. 


wParam 
lParam 
Returns 


‘DWORD: A pointer to a message structure. 


WORD: Always NULL. 
AN 


The function should return TRUE (nonzero) if the hook function processed the message, FALSE 
if no action was taken. This is the only application specific hook function. The hook function can 
be within the program, and does not have to be in a DLL. ba 


WM _SYSMSGFILTER 


nCode 


int FAR PASCAL FilterFunc(int nCode, WORD wParam, DWORD Param) ; : 
int: Must be one of the values listed in Table 8-5. - . 
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MSGF_DIALOGBOX 
-MSGF_MENU | 
_MSGF_MESSAGEBOX . 


The! message being processed is rom a tdalog Bee 
The message being processed i is mouse or keyboard input from a menu. 
_ The message being processed | is from a message box. 


Table 8-5. WM_SYSMSGFILTER nCode Values. 


wParam 
lParam 


Returns 


Example 


LIBRARY 


DESCRIPTION 


EXETYPE 
STUB 
CODE 
DATA ; 
HEAPSIZE 
EXPORTS 


WORD: Always NULL. 


| _ DWORD: A pointer to a message structure. Filter processes messages for all menus, message 
~ boxes, and dialog boxes. Similar to WH_ MSGFILTER, but applies system-wide. The hook function 


must be ina DLL. 
The filter function should return TRUE (one) if the message ' was processed, FALSE (zero) 
otherwise. 

This type of filter processes messages for all menus, message bikes, and dialog boxes. Similar 


- toWH _MSGFILTER, but applies system-wide. The hook function must be ina DLL. 


This example sets a hook function when the user clicks the “Do It!” menu item. The hook function 
intercepts Windows’ WM__ PAINT messages to every application running on the system. Any win- 
dow receiving a WM_PAINT message has its client area outlined with a red line by the hook 
function. This i is usually repainted by the window’ 's own painting logic, although the outline may 


” persist in windows that do not repaint the entire client area every time a WM_PAINT message is 

__ received. The outlining will continue until the “Do It!” menu item is clicked a second time and the 

hook function is removed. The hook function is placed in a dynamic link library (DLL) called 

MSGDLL. DLL. The definition file specifies “LIBRARY” rather than “NAME.” No stack size is 

‘given, as DLLs use the calling program's stack. The DATA segment is set as “SINGLE” as there 

will never be multiple instances of a DLL. Finally, the hook function is listed as an ca Bei 
Bs function. The following code i is the DLL Definition file, MSGDLL.DEF 


MSGDLL - 
‘dll of message hooke# 


- WINDOWS 
- "WINSTUB.EXE' 


PRELOAD MOVEABLE DISCARDABLE: — 7 . 7 
PRELOAD MOVEABLE SINGLE © Si ; : 
1024 

SetHook 

FreeHook 

MsgFilterFunc - 


To compile the DLL, a separate NMAKE file is created. The key difference is ‘that the com- 
piler switch -ASw is set to check that the stack segment and data segments to be assumed differ- 
ent. This example also shows the debugging switches set. The CodeView for Windows application 


~ will allow DLLs to be viewed and debugged i in the same manner as conventional Windows pro- 


grams, 


# make file for ‘msgdLl library 


ALL: msgdllcdll 


CFLAGS=-c -D LINT_ARGS -ASw Bass ~Od- ~Gsw mW 
LFLAGS=/NOD /co /align:16 - - 


msgdll. obj 


msgdll. dtl: 


adit. eet 


$(cc) SCCFLAGS) macau c 


msgdll.obj msgdll.def 


link $(LFLAGS) Bek had pibentr ys: msgdtl. dlt,. NUL, _ bibw sdilcew, msgdll 


re msgdLll.dllt- 
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The hook function is defined in the MSGDLL.C file. The mandatory DLL LibMain() function 
just unlocks the data segment of the library and returns. The hook function called 
MsgFilterfunc() waits until a WM_PAINT message is intercepted, and then paints the client area. 
The window handle for the window to receive the WM_PAINT message is retrieved from the msg 
structure. A pointer to this message structure data is passed in the [Param parameter when the 
hook function is called. : 


7% msgdlt.c message filter dll */ " 
Hinclude <windows.h> Deo he gas 


HANDLE hinstanceDll ; 
FARPROC LpOldHook ; 


int FAR PASCAL LibMain CHANDLE hInstance, WORD wDataSeg, WORD wHeapSize, 
LPSTR LpszCmdLine) 


{ 
if (wHeapSize > 0) 
UnlockData (0) ; 
hInstanceDLL = hInstance ; 
return (1) ; 
} ; 


void FAR PASCAL SetHook (LPSTR LpsHookName, int nHookType) — 

{ : 
FARPROC LpHook ; 
LpHook = GetProcAddress ChInstanceDLL, LpsHookName) ; 
LpOlLdHook = SetWindowsHook (nHookType, LpHook) ; 

} 

void FAR PASCAL FreeHook (LPSTR LpsHookName, int nHookType) 

{ 
FARPROC LpHook ; 
LpHook = GetProcAddress (hinstanceDll, LpsHookName) ; 
UnhookWindowsHook (nHookType, LpHook) ; 

} 


void FAR PASCAL MsgFilterFunc (int nCode, WORD wParam, DWORD lParam) 
{ 


LPMSG msg ; 

HDC hoc ; 
HPEN hRedPen ; 
RECT rClient ; 
static FARPROC lpHook ; 
DWORD dwTtest ; 


if (nCode != HC_ACTION) 
DefHookProc (nCode, wParam, LParam, &lpOldHook) ; 
else if (nCode >= 0) /* nCode negative, then no action */ 


msg = (LPMSG) lParam; _/* (Param holds message address */ 
if (msg->message == WM_PAINT) 
t 


hDC = GetDC (msg->hwnd) ; /* Outline the client area */ 
GetClientKect (msg->hwnd, &rClient) ; 
hRedPen = CreatePen (PS. SOLID, 3, RGB (255, Q, 0)) ; 
SelectObject ChDC,. aRedren? 7 
MoveTo (hDC, 0, 0) ; 
LineTo C(hDdC, <clAgnes right - 2, 0) ; 
LineTo (hDC, rClient.right - 2, rctient. botton - - 2) ; 
. LineTo (hoc, 0, retrenrs bottom — 2) ; 
, LineTo C(hbC, Q, 0); 
=F DeleteObject ChRedPen) : 
~ReteaseDC Giegs7tunds noes 


a 


- 253 


WINDOWS API BIBLE 


The C program calling the hook function must reference the function’s name in the defini- 
"tion file as “imported” from the DLL. The hooking and unhooking functions are also referenced. 


=e, } 
) 
‘peturn 3° 
| , 
NAME GENERIC 
DESCRIPTION .'generic windows program! 
EXETYPE . WINDOWS 
STUB ; "WINSTUB.EXE' 
CODE | ' PRELOAD MOVEABLE 
DATA. PRELOAD MOVEABLE MULTIPLE 
HEAPSIZE 1024 
STACKSIZE 4096. 
EXPORTS WndProc 


IMPORTS MSGDLL. eneeiceweune 
; : MSGDLL.SetHook 
_BSGDLL. FreeHook 


The C program’s make file, header file, and resource file are eal standard. No reference to the . 
- DLL containing the hook function i is needed i in these files. The following code i is the Man file for..8 08 oP. 


~ the C program. 
ALL: generic.exe ~ 
CFLAGS=-c -—D LINT_ARGS -Zi -Od -Gsw ~w2 
LFLAGS=/NOD /co 


generic.obj : generic.c generic.h 
$(CC) SCCFLAGS) generic.c 


generic.res: generic.rc generic.ico 
re -r generic.rc 


generic.exe : generic.obj- generic. def generic.res 
Link SCLFLAGS) generic, , soa slibcew, generic - 
re generic.res 


‘The following code is the resourée file. | 
/* generic.rc | - */ i . Aik 


_#include <windows.h> 
'#include “generic.h" 


generic: ICON generic.ico 
' generic Ne, 4 MENU ge Pe 
BEGIN. ors Aepanit oo 
- MENUITEM “&Do rt _  IDM_DOIT 
MENUITEM "&Quit", : IDM_QUIT 
END 


The following code is the header file. 


/* generic.h''. */) 


Adefine IDM_DOIT. 1 - Z "7 * menu item id values */ 


4define IDM_QUIT 2 
/* global variables */ 
int ghInstance ; 4 
ener: gszAppName C] = “generic"'; 
/* function prototypes */ . 
tone FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 


~The program sets the message hook function when the “Do It!” menu item is clicked. The 
hook function is unhooked the second time the menu item is selected, or when the program exits, 
if it is still active. Note that no changes are required to the message loop to pass messages to the 
hook function. Windows takes care of this: ‘reference when the SetWindowsHook() function is 
called, and removes it when the UnhookWindowsHook() function is called. 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG \Param) 
{ 


_} 


static BOOL bHooked = FALSE ; 
switch (iMessage) /* process windows messages */ 


case WM_COMMAND: /* process menu items */ 
: switch (wParam) , 


case IDM_DOIT: 
if (bHooked) 
{ 


FreeHook ("msgFilterFunc", WH_GETMESSAGE) ; 
bHooked = FALSE ; 
MessageBox (hWnd, "No hook function now.", 


“Unhooked", MB_OK) ; 
} 
else 
¢ 
SetHook C"MsgFilterFunc", WH_GETMESSAGE) ; 
bHooked = TRUE ; 
MessageBox (hWnd, “A hook function installed.", 
“Hooked”, MB_OK) ; 
} 
break ; 


case IDM_QUIT: 
DestroyWindow (hWnd) ; 
‘break ; 
} A 
break ; . 
case WM_DESTROY: /* stop application */ 
if (bHooked) 
FreeHook CmsgkeyboardFunc", WH_KEYBOARD) ; 
PostQuitMessage (0) ; 
break ; 
default: — /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return COL) ; 


TRANSLATEMESSAGE | Wing. Wingo Wing. 
Purpose. Generates WM_CHAR, WM_SYSCHAR, WM epEODCHAt, and WM_SYSDEADCHAR messages © 
when a virtual key code is received. | 
Syntax BOOL TranslateMessage(LPMSG IpMsq), 
Description - The low-level Windows drivers generate virtual key messages (VK_TAB, etc.) when a key is 

- pressed. TranslateMessage() posts the corresponding WM_CHAR code on the applications mes- 

sage queue when a virtual key code is received. 

Uses Normally, part of the program’s message loop. Ifyou vas not use the WM_CHAR messages, you can 
- leave this function out of the message loop. 
Returns ’ BOOL. TRUE if the message was translated. FALSE if not. 
See Also DispatchMessage(), GetMessage(), PeekMessage() 
Parameters 7 = Wo 
lpMsg LPMSG: . A pointer to a MSG message structure. This is the message data fetched from the 


application’s message queue by GetMessage() or PeekMessage. The message data is not altered 
by TranslateMessage(). The new WM_CHAR messages are placed on the message queue for sepa- 
rate processing. 


Related Messages The virtual key codes, WM_! CHAR, WM_SYSCHAR, WM_DEADCHAR, and WM_SYSDEADCHAR. 


Example 


This is a typical message loop from the end of a program’s WinMain() function. 
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while (GetMessage (&msg, NULL, 0, 0)) 
{ 


eo 
TranslateMessage (&msg) ; 


DispatchMessage (&msg) ; 


+ 
-UNnHOOKWINDowsHooK = m Win 2.0 mWin30 mWin3l 

Purpose - - Removes a message hook function from the system. 

Syntax BOOL UnhookWindowsHook(int nHook, FARPROC IpfnHlook); 

Description There can be any’ number of message hook functions installed of any one type. 
UnhookWindowsHook() removes one message from the chain. 

Uses Used within the DLL (dynamic link library) that sets the hook function. 

Returns BOOL. TRUE if the function was removed, FALSE on error. 

See Also. _ .. _ SetWindowsHook() has the complete eseEUOte of the different types of hook functions and a 
complete program example. : 

Parameters ae 

nHook int: Specifiés the type of filtering function, and what type of messages will be diverted to the 


filter before being sent to an application. The choices are Isited in Table 8-6. 


| 


WH_CALLWNDPROC 
WH_GETMESSAGE 


WH. JOURNALPLAYBACK: 


WH_JOURNALRECORD . 


WH_KEYBOARD 


WH_MSGFILTER 


-_ WH_SYSMSGFILTER. © 


Fiter py processes only messages sent by SendMessage( ). The hook function must be in a DLL. 


Filter processes messages immediately after the GetMessage| ) or PeekMessage() function 
is called in a program’s message loop. All messages are ai to the filter. The hook function 


_ must be in a DLL. 


Used with WH_, JOURNALRECORD. The filter function plays back an event message recorded 
with WH_JOURNALRECORD when an event is requested by the system Tessas queue. AN 
hook function must be in a DLL. 

Used with WH_JOURNALPLAYBACK. The fiter function records all messages processed in the 
system message queue. The stored messages can be played back bye a WH Sekt eo 


~ PLAYBACK hook. The hook function must be in a DEt. 


Filter processes WM | KEYDOWN and WM |_KEYUP messages received by GetMessage() or 
PeekMessage(). The hook function must be in a DLL. °. 


Filter processes messages for an application's menu, message boxes, and dialog boxes. This is ° 
. the only application- vee hook. The hook function does not have to be in a DLL and can be 


part of the program. ° 


.. Filter processes messages for all menus, message Sale and es boxes. Similar to 


WH_MSGFILTER, but applies system-wide. The hook function must be in a DLL. 


Table 8-6. UnhookWindowsHook( ‘) Hook Types. 


{ 


lpfnHook FARPROC: The procedure- hrighanics address af the hook function. 


Related Messages. All Windows messages. 3S 
Example - a the amples under the DeftlookProc() and Siindowstosk( function  deseitions 
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WAITMESSAGE — | | mWin2.0 mWin3.0 wWin31 


Purpose Yields control to any other application. 

Syntax void WaitMessage(void); 

Description WaitMessage() tells Windows to switch control to another application. Messages to other appli- 
cations are then processed. This is the most passive of the three functions Windows provides to 
switch control between running programs. The other two are GetMessage() and PeekMessage(). 

Uses’ Useful in small utility programs where it is desirable to give up control as often as possible to 
minimize the slowdown of the system due to having the utility program running. You can also use 
the function to wait for a specific message, such as a mouse movement. 

Returns No returned value (void). 

See Also GetMessage(), PeekMessage(). 

Paranneters None (void). 

Related Messages Any message received by the application calling WaitMessage() will resume message processing. 

Notes Any time control is yielded to another program by GetMessage(), PeekMessage(), or 
WaitMessage(), the stack and memory segments are subject to being moved in memory. Local 
variables and pointers to memory may be invalid when control is returned to the program. 

Example When the user clicks the “Do It!” menu item, PeekMessage() is used to clear any waiting mes- 


sages from the application’s message queue. The application then just sits there, waiting for any 
message (WaitMessage() call). If any key is pressed, or the mouse is moved, the text “Got a © 
message!” appears in the window’s client area and execution continues. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


static HDC hdc ; 
MSG msg ; 
char cBuf £128] ; 
switch CiMessage) /* process windows messages */ 
{ , 
- case WM_COMMAND: /7/* process menu items */ 
switch (wParam) ; 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
while CheekMessage C&msg, hWnd, 0, 0,.PM_REMOVE)) 
/* clear any waiting messages */ 
WaitMessage ©; /* now wait for one */ 
hDC = GetdCc Chine) ; 
TextOut (hDdDC, 0, 0, "Got a message!", 14) ; 
ReleaseDC (hWnd, HDC) ; , 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} 
breek ; ; : 
case WM_DESTROY: -/* stop application */ 
PostQuitMessage (0) >; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, (Param) ; 
} ” ! 


return (COL) ; 
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Windows uses a lot of messages. These messages range from common ones, like WM_CREATE that are used in most 
applications, to obscure messages that you may never use. This chapter documents all of them (except for the DDE 
messages explained in Chapter 30) with example programs at the start of each group of related messages. If you are 
beginning to learn Windows, you may want to spend some time just reading the Purpose. sections for each of the 
messages. They will give you an idea of what the different types of messages can do. Later, when you need a message, 
you can look up the right one and its exact syntax. 


Transmitted Messages 


Windows messages are categorized into ten groups. Each group has a different prefix, such as BM_ for button mes- 
sage. Table 9-1 gives each of the message prefixes and the message type that corresponds. 


BM_ Button message. Sent t toa child imdow sites corel to do some action, sich as cena the 
button’s text string. ; 

BN_ Button notification code. Received by the application’s WndProc() function from a child window button 
control. An example is BN_CLICKED, which means the button was clicked. 

CB_ Combo box message. Sent to a combo box control to cause some action, such as adding an item. 

CBN_ Combo box notification code. Received by the application’s WndProc() function from a combo box | 
control as notification that some action occurred, such as the selection was changed. 

DM_ Dialog box message. There are only two of these, both dealing with the default pushbutton control. 
Dialog boxes and their child windows send and receive normal window messages for most actions. 

EM. Edit.control message. Sent to a child window edit control to cause some action, such as changing the 

text string. 

EN_ Edit control notification code. Received by the application's WndProc() fecicn as notification that some 
action occurred to an edit control (for example, if the edit control was scrolled or text was added). 

LB. . List box message. Sent to a list box control to cause some action, such as deleting an item. 

LBN_ List box notification code. Received by the application’s WndProc() function as notification that some 


action occurred to the list box control, such as the user selected an item. 


WM_ All other Windows messages. This includes the WM_DDE messages for dynamic data exchange 
(Chapter 30, defined in DDE.H) and the WM_MDI messages for the multiple document interface. The 
MDI messages are documented in this chapter, but discussed more fully in Chapter 29. 


Table 9-1. Windows Message Types. . - 


Messages can be either sent or received. Most messages tend to be either sent ina SendMessage() function callor . 
received in a message processing function, such as WndProc(). The message descriptions that follow show the most 
common situations. You can choose either to send the message to the application’s message queue with Post- 
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Message() or send it directly to the application’s message processing function with SendMessage(). SendMessage() is 
_ required if you send a message to a control, such as a button. 


Transmitted Button Message Summary 


Windows provides five messages that you can send to a button control either to change the button’s status (checked, 
unchecked, etc.) or to find the current status. Table 9-2 gives a summary of the messages. 


BM_GETCHECK Find out ti a = ae or eee box is sectad: 


BM_GETSTATE Find out if a button is highlighted (by a mouse click or spacebar action). 
BM_SETCHECK Change a radio button or check box to/from checked/unchecked. 
BM_SETSTATE Highlight or remove highlighting from a button. 

BM_SETSTYLE Change the style of a button control, 


Table 9-2. Transmitted Button Messages. 


_ Abutton’s text string is usually changed with the SetWindowText() function, not by transmitting a WM_SETTEXT 
_ message to the button control. Listing 9-1 gives an example WndProc() function that uses three of the BM_ messages 
to change a button’s style, set the button to a checked state, and confirm that the button is checked using _ 
BM_GETSTATE. SendMessage() is used to transmit the messages to the button control. 


& Listing 9-1. Example Using Transmitted Button Messages 
tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD ar arem? LONG lParam) 
{ 


static HWND hButton ; 


HOC hDC ; 
int nButtonState - 
switch (iMessage) , /* process windows messages */ 


case WM_CREATE: : 
hButton = CreateWindow ("“BUTTON", “Button Text", 
WS_CHILD |{ WS_VISIBLE | BS_RADIOBUTTON, 
10, 10, 100, 40, hWnd, 10%, ghinstance, NULL) ; 
Shomer ndos chButton, SW SHOW) ; 


break ; 
case WM _ COMMAND: . /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the “Do it" menu item */ 


SendMessage (hButton, BM_SETSTYLE, 
CWORD) BS_CHECKBOX, 1L) ; 
SendMessage ChButton, BM_SETCHECK, 1, OL) ; 
nButtonState = SendMessage (hButton, 
BM_GETSTATE, 0, OL) ; 
hDC = GetDC (hWnd) ; 
if (nButtonState) ae 
TextOut ChDdDC, 10, 120, 
"Button is highlighted.", 22) ; 
else , 
TextOut Choc, 10, 120, 
spptten is Not highlighted.", 26) ; 
ReleaseDC ChWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow ChWnd) ; 
break ; 
} ’ 
break ; 
case WM_DESTROY: 7 ‘/*® stop application */ 
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PostQuitMessage (0) ; 
break ; ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, Param) ; 


+ 
return (OL) ; 


Figure 9-1 shows the example program after the user clicked the “Do It!” menu 
item. Note that the radio button has been changed to a check box style, showing a [-[-~ generic. [> [+ 
square check box in place of the radio button circle. The check box has an “X” in the 
center, because a BM_ SETCHECK message was sent. 


Button Text 


BM _ GETCHECK mWin2.0 8 Win3.0 mWin3l 

Purpose Determines if a radio button or check box control is checked. 

Syntax dwReturned = SendMessage (HWND hControl, BM_GET- 
CHECK, WORD wParam, DWORD /Param); ' see ee 

Returns DWORD. Nonzero if the control is checked, zero if checked. een ee 
_ Always returns zero if a pushbutton control i is tested (nocheck Figure 9-1. Sending a 
box). Message to a Child Window 

Parameters Control. 

hControl HWND: The window handle of the button control. 

wParam WORD: Not used. Set equal to 0. 

lParam DWORD: Not used. Set equal to OL. 


Related Messages BM_SETCHECK 


BM_GETSTATE BWin2.0 mWin3.0 mWin3.1 
Purpose Determines if a button control has been highlighted. Highlighting occurs when the user clicks 
7 the button with the mouse, or presses the spacebar when a button has the input focus. 

Syntax dwReturned = SendMessage (HWND hControl, BM_GETSTATE, WORD wParam, DWORD 
lParam) 

Returns DWORD, nonzero if the button is highlighted, zero if not. 

Parameters 

hControl HWND: The window handle of the button control. 

wParam WORD: Not used. Set equal to 0. 

[Param DWORD: Not used. Set equal to OL. 

BM_SETCHECK | wWin2.0 mWind0 mWin3l 
Purpose Checks or removes a checkmark from a radio button or check box control. Has no effect on push- 

. buttons. 

Syntax SendMessage (HWND hControl, BM_SETCHECK, WORD wParam, DWORD [Param) 

Returns DWORD. Is not used. 

Parameters 

hControl HWND: The window handle of the button control. 

wParam WORD: 0 to remove a checkmark. 1 to place a checkmark. 2 to gray a button control created with 

- the BS_AUTO3STATE or BS_8STATE style. 
lParam DWORD: Not used. Set equal to OL. 
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BM_SETSTATE | wWin2.0 8Win30 .mWin3.l 
Purpose Changes a button control to/from the highlighted state. 

Syntax SendMessage (HWND hControl, BM_SETSTATE, WORD wParam, DWORD cen). 

Returns DWORD. Not used. 

Parameters 

hControl HWND: The window handle of the button control. 

wParam WORD: 0 to remove highlighting. 1 to highlight the button control. 

lParam DWORD: Not used. Set equal to OL. 

BM_SETSTYLE mWin2.0 mWin3.0 mWin3.1 
Purpose Changes the style of a button control. 

Syntax SendMessage (HWND hControl, BM_SETSTYLE, WORD wParam, DWORD /Param) 

Returns DWORD. Not used. . 

Parameters 

hControl HWND: The window handle of the button control. . 
wParem WORD: The button control style to use. wParam can be set to any of the values listed in Table 9-3. 


3 BS_AUTOCHECKBOX Small recur button with text to ie right. The rectangle can be either open or re 
. This style toggles automatically between checked and open. 
BS_AUTORADIOBUTTON Small circular button with text to the right. The circle can be either filled or open. This style - 
toggles automatically between checked and open. 


y BS_AUTO3STATE . Smail rectangular button with text to the right. The button can be filed, grayed, or open, This 
. ey style toggles automatically between checked, grayed, and open. 
BS_CHECKBOX ‘ Small rectangular button with text to the right. The rectangle can either be open or checked. 
BS_DEFPUSHBUTTON Button with text in the center and with a defined (dark) border. 
BS_GROUPBOX A box with text at the upper left. Used to group other buttons. 
BS_LEFTTEXT Causes text to be on the left side of the button using the language library OR operator? 
BS_OWNERDRAW _ Designates a button that will be drawn by the program. Windows sends messages to request 
paint, invert, and disable. Use this style for custom button controls. 
BS_PUSHBUTTON Button with text in the center. \ 
BS_RADIOBUTTON Small circular button with text to the right. The circle can be either filled or open. 
BS_3STATE _ Small rectangular button with text to the right. The button can be filled, grayed, or open. 
Table 9-3. Button Styles. 
[Param DWORD: Specifies whether or not the button control should be redrawn. Set to IL to redraw the 


’ control (normal case), or set to OL to not redraw until the next WM_ PAINT cycle. 


Button Notification Codes 


When a button sends a WM_COMMAND message to its parent, it places the button ID value in the wParam value of 
the message. The ID value of the button is initially set in the CreateWindow() call by setting the hMenu parameter 
equal to the control's ID value. Note that hMenu is poorly named. Only parent and popup windows use this parameter 
_ to refer to a menu. The button ID values are usually defined in the program's header file. The numbers should be 
different from any of the menu item ID values because both buttons and menu items interact with the program via 
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WM_COMMAND messages. When the user clicks a button control, Windows sends a 
WM_COMMAND message. The button’s ID value is passed as the wParam param- 
eter, while [Param contains the button control’s window handle in the low-order 
word and a notification code like BN_DOUBLECLICKED in the high-order word. 
Listing 9-2 shows the WndProc() function of a program with two controls, a 
pushbutton, and a radio button. The text in the controls is changed when they are ‘ 
clicked with the mouse. The result, after double-clicking both controls, isshownin ] © pouble Clicked 2. ~~ 
Figure 9-2. Windows also sends WM_COMMAND messages for button controlswhen § , 
they are enabled, about to be painted, highlighted, or loose highlighting. You can 
intercept these messages for painting custom button images in place of the usual . Figure 9-2. Window Controls 
text and highlighting defaults. , Responding to Mouse Clicks. 


Sige Cee 
Pow que 


& Listing 9-2. Button Notification Codes 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HWND hButton, hRadioButton, hPickedButton ; 


switch (iMessage) /* process windows messages */ 
{ Fy 
case WM_CREATE: 
hButton = CreateWindow ("“BUTTON", “Button Text", 
WS_CHILD | WS_VISIBLE | BS_PUSHBUTTON, 
10, 10, 150, 40, hWnd, 100, ghInstance, NULL) ; 
ShowWindow (hButton, SW_SHOW) ; 
hRadioButton = CreateWindow ("BUTTON", "Button Text", 
WS_CHILD | WS_VISIBLE { BS_RADIOBUTTON, 
10, 60, 150, 40, hWnd, 101, ghInstance, NULL) ; 
ShowWindow (hRadioButton, SW_SHOW) ; 
break ; : 
case WM_COMMAND: /* process menu items and buttons */ 
switch (wParam) 
{ 


case 100: /* push button's id value */ 
hPickedButton = LOWORD (lParam) ; 
if CHIWORD (lParam) = = BN. CLICKED). : 
SetWindowText C(hPickedButton, "Clicked 1") 7 s 
break ;) \ 
case 101: /* radio pur Sons id value */ 
hPickedButton = LOWORD (lParam) ; 
if CHIWORD (lParam) = = BN_! cLicKed) 
. SetWindowText (hPickedButton, "Clicked 2") ; 
else if CHIWORD (lParam) == BN_DOUBLECLICKED) 
SetWindowText (hPickedButton, 
“Double Clicked 2") ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; . i URE 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; ‘ 
break ; : ; 
default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
} 


Button Notification Code Summary 


Table 9-4 summarizes the button notification codes. These are transmitted with WM_! COMMAND messages. The noti- 
fication code is sent as the high-order word of the /Param value sent with WM _COMMAND. The detailed descriptions 
of the notification codes follow ener after the table. 
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BN_CLICKED a Notification that a button control was clicked ye the mouse, or the spacebar was reseed ne 


; the control had the input focus. — 
BN_DISABLE = | Notification that a button control was disabled. 
BN_DOUBLECLICKED | Notification that a button control was double-clicked with the mouse, 
BN_HILITE © Notification that a button contro! will be highlighted. 
BN_PAINT Notification that a button control is about to be painted. 
BN_UNHILITE - Notification that a button control will loose its highlighting. 


Table 9-4. Button Notification Codes. 


Button Notification Code Descriptions — 


BN_CLICKED. mWin2.0 Win3d0 mWin3] 

Purpose Notification that a button control was clicked by the mouse, or the spacebar was pressed w when 
. the control had the input focus. 

Syntax Returned as part of a WM_COMMAND message, processed by the program’s message processing 

function (WndProc()). 
- Parameters Sin | 
wParam WORD: Contains the ID value for the control. This is the integer value set for the hMenu pa- 
rameter when CreateWindow() was called. 
lParam DWORD: The low-order word contains the handle of the button contro The high-order word 
, ‘ contains BN_CLICKED. 
BN_DISABLE Be Win2.0 wWind0 mWin31 
Purpose Notification that a button control was disabled. Button controls can be enabled and disabled with 
= ‘the EnableWindow() function. 
Syntax __ Returned as part of aWM_COMMAND message, processed by the pRoetem Ss message processing 
function (WndProc()). 
Parameters 
wParam WORD: Contains the ID value for the control. This is the integer value set for the h hitenu pa- 
i rameter when CreateWindow() was called. 
lParam DWORD: The low-order word contains the handle at the button control. The high-order word 
Bog contains BN_DISABLE. 

BN_DOUBLECLICKED 7 m@Win2.0 wWin3.0 om Win3.l 

Purpose Notification that a button control was double- clicked with the mouse. | 
Syntax: Returned as part of a WM_COMMAND message, processed by the program's message processing 
. _ function (WndProc()). 

Parameters . 

wParam WORD: Contains the ID value for the control. This is the integer value set for the hMenu param- 

. eter when CreateWindow() was called. 
lParam DWORD: The low-order word contains the handle of the button control. The Dene, word 


contains BN_ DOUBLECLICKED. 
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BN_HILITE mWin2.0 mWin30 mWin31 
Purpose Notification that a button control will be highlighted. This can be used for custom buttons to 


allow painting of a highlight image or bitmap. Custom buttons are created with the BS_OWNER- _ 
DRAW style when calling CreateWindow(). 


Syntax Returned as part of aWM_COMMAND message, processed by the program’s message processing 
function (WndProc()). 

Parameters 

wParam WORD: Contains the ID value for the control. This is the integer value set for the hMenu param- 
eter when CreateWindow() was called. 

lParam DWORD: The low-order word contains the handle of the button control. The high-order word 
contains BN_HILITE. 

BN_PAINT | mw Win2.0 m8Win3d.0 mWin3.1 

Purpose Notification that a button control is about to be painted. Custom buttons are created with the 


BS_OWNERDRAW style when calling CreateWindow(). See the example of owner-drawn menu 
items at the begining of Chapter 4, Menus, for the similar example. 


Syntax Returned as part of aWM_COMMAND message, processed by the program’s message processing 
function (WndProc()). 

Parameters . i 

wParam WORD: Contains the ID value for the control. This is the integer value set for the AMenu param- 
eter when CreateWindow() was called. . 

lParam DWORD: The low-order word contains the handle of the button control. The high-order word 
contains BN_PAINT. 

BN_UNHILITE mWin20 mWing0 mw Wind. 

Purpose Notification that a button control will lose its highlighting. This can be used by custom button 


controls to signal repainting of the button’s client area with the normal image. Custom buttons 
are created with the BS_OWNERDRAW style when calling CreateWindow(). 


Syntax . Returned as part of aWM_COMMAND message, processed by the program’s message processing 

| function (WndProc()). 

Parameters : 

wParam . WORD: Contains the ID value for the control. This is the integer value set for the hMenu param- 
eter when CreateWindow() was called. 


lParam -DWORD: The low-order word contains the handle of the button control. The high-order word 
. contains BN_UNHILITE. 


Combo Box Messages 


Combo boxes were added with the 3.0 version of Windows. Combo boxes combine an edit control at the top with a list 
box underneath it. The list box can be either visible all of the time (CBS_SIMPLE style) or visible only when the user 
clicks a button on the right side of the edit control (CBS_DROPDOWN style). A full description of all of the style 
possibilities is given in the CreateWindow() function description in Chapter 2, Creating Windows. 

Once created, a program communicates with a combo box by sending and receiving messages. Most of these 
* messages parallel similar messages for list boxes. The additional messages deal with the edit control at the top, which 
is used to display the most recent selection or allow editing of an entry in the list. Listing 9-3 provides a rudimentary 
example of creating and dealing with a combo box. When the user clicks the “Do It!” menu item, the list box is filled 


265 


WINDOWS API BIBLE 


with four text items. Ifan item from the list is selected, it is displayed in the combo box 
edit field at the top (this is automatic), and is also displayed at the bottom of the 
window. Figure 9-3 shows what the program ’s window looks like after the second item 
—in the list box is selected. . 

Note in the listing that the combo box style includes the WS_VSCROLL style, 
which adds a vertical scroll bar to the right side of the list box area. Also note that 
the combo box is given an ID value of 100, which is used in processing WM_COMMAND 
messages to identify which control sent the message. Normally, these ID values are 
defined in the program’s header file and have separate numbers from any menu item. 


Second String : 
First String _ i 


Second Stri 


The selected text is: 
Second String 


Figure 9-3. A Combo Box 
Control. 


© Listing 9-3. Sending and Receiving Messages from a Combo 
Box Control : 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ‘ 


static HWND — hComboBox ; 


HOC hDC ; 
int nSel ; 
char cBuf £30) ; 


switch (iMessage) /* process windows messages */ 
‘case WM_CREATE: | 
hComboBox = beeetcu indies ("CoMBOBOX", “Combo Text", 
WS_CHILD | WS_VISIBLE | CBS_SIMPLE | CBS_HASSTRINGS 
| WS_VSCROLL, 
10, 10, 180, 80, hWnd, 100, gninstannsy NULL) ; 
‘ShowWindow (hComboBox, SW_SHOW) ; 
break ; . 
case WM_COMMAND: 
switch (wParam) 
{ 
case 100: . /* Combo box id value */ 
if CHIWORD (lParam) == CBN_SELCHANGE) 
{ 


/* process menu items and bikeons */ 


hdc = 
nSel = 


GetDC ChWnd) ; 
(WORD) Sandhveeaue ChComboBox, 
CB_GETCURSEL, 0, OL) ; 
SendMessage ChComboBox, CB _GETLBTEXT, 
; nSel, been CLPSTR) cBuf) ; 
TextOut ChDC, , 120, 
"The. Sete cced text isi", 21); 
TextOut ChDC, 10, 140, cBuf, Lstrlen (cBuf)) ; 
ReleaseDC Chwnd® hdc) ; 


_ } 
: break ; 
case IDM_DOIT: 


SendMessage (hComboBox, 
SendMessage (hComboBox, 
CDWORD) (CLPSTR) 
SendMessage (hComboBox, 
CDWORD) (LPSTR) 
SendMessage (hComboBox, 
CDWORD) (LPSTR) 


SendMessage (hComboBox, 


CDWORD) (LPSTR> 
SendMessage Chegmboboxs 
break ; 
case IDM_QUIT: /k eend 
pestroxmindey:! Chiind) ; 
break ; ; 
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CB_RESETCONTENT, O, OL) ; 
CB_ADDSTRING, O, 

“First String") ;. 
CB_ADDSTRING, 0, 

"Second String") ; 
CB_ADDSTRING, 0, 

"Last String") ; 

cB_ INSERTSTRING, 2, 
“Inserted") ; 
CB_SHOWDROPDOWN, TRUE, OL) ; 


end of application message x/ 
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break ; 


case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 


default: /* default windows message processing */ 
: return DefWindowProc ChWnd, iMessage, wParam, LParam) ; 
} 
return (OL) ; 
} 


Owner-Redrawn Combo Boxes 

Most combo boxes keep their own copies of the strings used in the list box if the CBS_HASSTRINGS style is used in 
creating the combo box. If this style is not selected, the combo box has the OWNERREDRAW style, which means that 
the calling program is responsible for painting every item in the combo box. This is ideal for selecting colors from a 
palette (showing color bars for the entries in the combo box’s list box) or graphic object selection. Combo boxes that 
are OWNERREDRAW store only a 32-bit value for each element of the combo box. This value can have any meaning 
desired by the programmer, Common uses are RGB color values and handles to bitmaps. When Windows needs to 
paint one of the owner-redrawn items, Windows sends a WM_DRAWITEM message. The [Param value passed with the 
message contains a pointer to a DRAWITEMSTRUCT structure. The 32-bit value for the combo box item ends up in the 
itemData element of the structure. 


/* DRAWITEMSTRUCT for ownerdraw */ 
typedef struct tagDRAWITEMSTRUCT 
t: 


WORD CtlType; /* ODT_MENU, ODT_LISTBOX, ODT_COMBOBOX, or ODT_BUTTON */ 


WORD CtLlID; /* the control id for the List box, combo box, button */ 
WORD itemID; /* the item's id number in the List or combo box */ 
WORD itemAction; ; /* ODA_DRAWITEM, ODA_SELECT, or ODA_FOCUS */ 

“WORD itemState; /* ODS SELECTED, ODS_GRAYED, ODS_DISABLED, ODS_CHECKED */ 
HWND hwndItem; /* the item's handle */ /* or ODS_FOCUS */ 
HDC hDC; /* the item's device context */ 

RECT rcltem; ; /* the bounding rectangle of the item */ 
DWORD itemData; /* 32-bit data goes here */ 


} DRAWITEMSTRUCT; 
typedef DRAWITEMSTRUCT NEAR *PDRAWITEMSTRUCT; 
typedef DRAWITEMSTRUCT FAR *LPDRAWITEMSTRUCT; 


The structure also contains the size of the item as a rectangle, the device context, and coded information as to 
what type of paint operation to do. These options are in the itemAction and itemState elements of the structure. 
There are other similar structures defined in WINDOWS.H for passing information on sizing items, deleting items, 
and sorting them in the list box. These structures are used less frequently. The other structures are shown with their 
corresponding messages later in this section. . 

Windows sends WM_DRAWITEM messages for each combo box item that needs to be updated. If the items are to 
be sorted, WM_COMPAREITEM messages will be sent to add a new item, as simple ASCII sort order cannot be used. 
WM_DELETEITEM messages are sent to the program if items are to be removed. Finally, if the CBS_OWNER- 
DRAWVARIABLE style is used, the items in the combo box do not have to be all the same height. WM_MEASURE- 
ITEM messages will be sent when an item is inserted to set the item’s size. Figure 9-4 shows an owner-redrawn combo 
box that allows the selection of one of four colors. This is a drop down combo box, so . 
that only the selected color is normally visible. The list box showing all of the colors fail “generic . dy [s 
is hidden until the down arrow on the right side of the selection box is clicked. poow gut 

The trick behind this application is that the color of each of the selection items - 
can be stored as a 32-bit value. When Windows needs to paint one of the list box 
items, or the top selection box, it sends a WM_DRAWITEM message. The WndProc() 
function intercepts these and finds the pointer to a DRAWITEMSTRUCT as the 
lParam value. The 32-bit coded value for the RGB color is found in the 7temData 
element. All the WndProc() function has to do is paint the given rectangle withthe Figure 9-4. An Owner- 
color specified by the RGB value. Redrawn Combo Box. 
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Listing 9-4 shows the WndProc() function that creates and updates the owner-redrawn combo box: As an added 
example, when the user clicks the “Do It!” menu item, one of the color values is changed to a new RGB value, matching 
yellow. Note that WM_MEASUREITEM messages are also processed. This is Windows’ way of finding out the vertical 
size of an item, measured in pixels. In processing either WM_DRAWITEM or WM_MEASUREITEM messages, an item 
number of -1 refers to the top edit control of the combo box. 


> Listing 9-4. Combo Box Example 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


static HWND . hComboBox ; 

LPDRAWITEMSTRUCT LpDIS ; 

PCHEASUREE TENS TRUE S LpMIS a 

HBRUSH hBrush ; 

RECT reSaatler ; 

switch (iMessage) /* process windows messages */ - 


case WM_CREATE: : 

_ hComboBox = CreateWindow ("COMBOBOX", “Combo Text", 
WS_CHILD | WS_VISIBLE | CBS_' OWNERDRAWFIXED | 
CBS_DROPDGWNLIST | WS_VSCROLL, 

10, 10, 180, 80, hWnd, 100, ghInstance, NULL) + 

ShowWindow (hComboBox, SW_SHOW) ; 

/* add in all of the items, setting the 32 values = RGB color */ 
SendMessage (hComboBox, CB_RESETCONTENT, 0, OL) ; 
SendMessage SmEORDOB OX: CB_ADDSTRING, QO, 

RGB (0, 0, 0)) ; 
SendMessage (hComboBox, cB. _ADDSTRING, 0, 

RGB (255, 0, 0)) ; 
SendMessage (hComboBox, CB_ADDSTRING, 0, 

RGB (0, 255, 0)) ; 
SendMessage (ChComboBox, CB_INSERTSTRING, 2, 

_ RGB (0, 0, 255)) ; 

SendMessage (hComboBox, CB_SETCURSEL, 2, OL) ; 


break ; 
case WM_COMMAND: /* process menu items and buttons */ 
switch (wParam) 
4 
case IDM_DOIT: /* change an item's 32 bit value (color)*/ 


SendMessage (hComboBox, CB_SETITEMDATA, 2, 
RGB(255, 255, 0)) ; z 


break ; : 
case IDM_QUIT: /* send end of application message */ 
, DestroyWindow (hWnd) ; 
break ; 
} ; ° 
break ; 
case WM_DRAWITEM: :. 
LpDIS = (LPDRAWITEMSTRUCT) lParam ; /* get pointer to DIS */ 
switch (LpDIS->itemAction) . 
{ : 
case ODA_DRAWENTIRE: /* get RGB value */ 


hBrush = CreateSolidBrush (lpDIS->itemData) ; 
CopyRect (C(LPRECT) &rcSmaller, 
CLPRECT) &lLpDIS—->rcItem) ; 
/* Leave room for border */ 
InflateRect (C(LPRECT) &rcSmaller, -2, -2) ; 
/* paint the item */ 
FillRect (lpDIS->hDC, CLPRECT) &rcSmaller, 
hBrush). ; 
pers teeuiecs ChBrush) ; 
break ; 
case ODA “SELECT: 
if (lpDIS->itemState & ODS SELECTED) 
hBrush = GetStockObject (BLACK_]| BRUSH) ; 
else /* eraser */ 
hBrush = GetStockObject (WHITE_BRUSH) ; 
FrameRect (lpDIS<>hDC, (LPRECT) &lpDIS->rciten, 
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hBrush) ; 
DeleteObject (hBrush) ; 
break ; : i 
ae 
break ; 
case WM_MEASUREITEM: ‘ 
LpMIS = CLPMEASUREITEMSTRUCT) lParam ; 


if ClpMIS->itemID == -1) /* if the top edit control */ 
LpMIS->itemHeight = 25 ; 
else /* item in the List box */° 
LpMIS->itemHeight = 20 ; 
break ; ; 
’ case WM_DESTROY: ; /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 


return DefWindowProc <hWnd, iMessage, wParam, lParam) ; 
} ; ; 
return (QL) ; 
} 


Combo Box Message Summary 


ey ange am uipose 
CB_ADDSTRING Adds a string to a combo box. 
CB_DELETESTRING Deletes a string from the combo box. 
CB_DIR- Fills the combo box with file names from a directory search. 
CB_FINDSTRING Locates the first string in the list box of the combo box that matches a given set of starting characters. 
CB_GETCOUNT Returns the number of items in the list box of acombo box. __ 
CB_GETCURSEL Finds the index number of the currently selected item in the list box of a combo box. 
CB_GETDROPPED- Retrieves the screen coordinates of the list box of a combo box in dropped-down position. 
CONTROLRECT (Win 3.1) e 8 
CB_GETEDITSEL: Returns the range of characters selected within the edit contro! of the combo box. 
CB_GETEXTENDEDUI Determines if a combo box has the default or extended user interface. (Win 3.1) 
CB_GETITEMDATA Retrieves the 32-bit value associated with an item in an owner-redrawn combo box. 
CB_GETITEMHEIGHT Determines the height of an item in a combo box control. (Win 3.1) 
CB_GETLBTEXT Retrieves the string held in an item in the list box of a combo box. 
CB_GET LBTEXTLEN Finds the number of characters in a string in the list box of a combo box. 
CB_INSERTSTRING Adds a new string or 32-bit item to the list box of a combo box. 
CB_LIMITTEXT ~ Sets the maximum number of characters that a user can enter in the edit control of the combo box. 
CB_RESETCONTENT Removes all elements from the list box of a combo box and frees memory associated with the items. 
CB_SELECTSTRING | Finds a matching string in the combo box list, and displays it in the edit control of the combo box. 
CB_SETCURSEL . Selects and highlights an item in the list box of a combo box. . 
CB_SETEDITSEL Selects a range of characters in the edit control of a combo box. 
CB_SETEXTENDEDUI Selects either the default or extended user interface for a combo box. (Win 3.1) 
CB_SETITEMDATA Changes the 32-bit value associated with a list box item of a combo box created with the owner- 

redrawn style. 


CB_SETITEMHEIGHT Sets the height of either the top edit contro! or list box items in a combo box control. (Win 3.1) 


Table 9-5. Combo Box Message Summary. 
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One other message worth knowing about is WM_SETREDRAW, which allows the combo box to be temporarily 
inhibited from redrawing the contents as additions and subtractions are made. WM_SETREDRAW speeds up the 
redrawing of the contents and reduces the distracting “flicker” of different items showing up one at a time. 
WM_SETREDRAW is documented at the end of this chapter, due to the WM prefix. 


Combo Box Message Descriptions 


CB_ADDSTRING 


Purpose 
Syntax 


Returns 


Parameters _ 


hControl 
wParam 
lParam 


CB_DELETESTRING 


Purpose — 
Syntax 


Returns 


Parameters 
hControl 


wParam 
lParam 


CB_DIR 
Purpose 
Syntax 
Returns | 


Parameters) 


hControl 
wParam 


\ 


OWin2.0 mWin30 mWin3] 
Adds a string to a combo box. If the = OnibO box has the CBS_SORT style, the string is placed in the 
list and the list is re-sorted. Otherwise, the string is added to the end of the list. 

dwReturned = SendMessage (HWND hControl, CB_LADDSTRING, WORD uae DWORD 
lParam)  _ ae 


DWORD. The returned value is the index of the new pei in the combo box. Returns 
CB_ERRSPACE if there is not enough memory to store the value. Returns CB_ERR on any other _ 
error. 


~ HWND: The window handle of the combo box control. 


WORD: Not used. Set to 0. 


DWORD: For combo boxes with the CBS_HASSTRING style, [Param contains a pointer to a null- 
terminated string for a text item. For other styles, [Param encodes a 32-bit value for the item. 
This can be retrieved when processing WM_DRAWITEM messages as the itemData element of 
the DRAWITEMSTRUCT structure passed with the message. 


OWin2.0 mWin38.0 m8 Win3l 
Deletes an item from the combo box. 


dwReturned = SendMessage (HWND hControl, CB_DELETESTRING, WORD wParam, DWORD : 
lParam) 


DWORD. The number of items remaining in the list. Returns CB_ERR if ioparane’ is not avalid list 
element index. 


HWND: The window handle of the combo box control. 
WORD: Contains the index to the list element. 0 for the first item. 


‘DWORD: Not used. Set to OL. 


For combo boxes with the CBS_HASSTRINGS style, this mniesiage will free memory associated 
with the deleted item. 


OWin2.0 m#8Win30 Wind] 


Fills the combo box with file names froin a directory search. 


dwReturned = SendMessage (HWND hControl, CB_DIR, WORD wParam, DWORD lParam) 


DWORD. The number of items displayed minus 1. Returns CB_ERRSPACE if there is not enough 
memory for the list. Returns CB __ERR for any other error. 


HWND: The window handle of the combo box control. 


~ WORD: Contains the DOS file attribute value. The values can be combined by using the C lan- 
Buage aes OR peer (i). se attributes are listed in sable 9-6, : 
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0x0000 Read/wite data files with no other attributes set (normal files). 


Ox0001 Read only files. 

Ox0002 Hidden files. 

0x0004 ~=s—i(‘é‘é‘é«S stem fless 

0x0010 Subdirectories. 

0x0020 Archived files. 

0x2000 LB_DIR flag. Piaces messages associated with filling the ist box on the applications message queue, rather 
than sending them directly. 

0x4000 Drives. 


0x8000 Exclusive bit. If this is set, only the specified file attribute type is recovered. If not set, normal files are 
displayed in addition to the types listed. 


Table 9-6. File Attribute Flags. 


lParam DWORD: A pointer to a file search edification a string (like Kk 40 op TXT”). This can be a full 
directory specification. See the example under the DigDirListComboBox() function description 
in Chapter 20, MS-DOS and Disk File Access. 


CB_FINDSTRING OWin2.0 mWin3.0 mWin3l 

Purpose Locates the first string in the list box that matches a given set of starting characters. 

Syntax dwReturned = SendMessage (HWND hControl, CB_FINDSTRING, WORD wParam, DWORD 
lParam) 

Returns DWORD. The index of the first string in the list box that starts with the characters in the dong 


pointed to by /Param. 0 for the first item, 1 for the second, etc. Returns CB_ERR (—1) if the 
search did not find a match. For owner-drawn combo boxes without the CBS_HASSTRINGS style, 
the message returns the index of the item that has a matching 32-bit value to the one specified in 


Harem. 

Parameters ; 

hContrel HWND: The window handle of the combo box control. 

wParam WORD: The index of the list box item before the first item to start the search. The search will 
wrap around if the end of the list is passed without a match. Set wParam = —1 to search the 
entire list. You can find multiple occurrences of a matching string by repeatedly sending this — 
message, each time starting from the previous match. The search will loop from the bottom to the 
top of the list until the entire list has been searched. 

lParam DWORD: A pointer to a null-terminated string. In order to have a match, the characters in this 
string must all be matched by the beginning characters of an item i in the list. 

CB_GETCOUNT | OWin2.0 mWind0 eB Wind.l 

Purpose Returns the number of items in the list box of a combo box. : 

Syntax _ dwReturned = SendMessage (HWND hControl, CB_GETCOUNT, WORD wParam, DWORD 

; lParam) 

Returns DWORD. The number of items in the list box. Returns CB_ERR on error. 

Parameters ; aes . 

hControl _ HWND: The window handle of the combo box control: 
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wParam WORD: Not used. Set equal to 0. 


‘lParam DWORD: Not used. Set equal to OL. 
CB_GETCURSEL | OWin2.0 mWin3.0 mWin31- 
' Purpose Finds the index number of the currently selected item in the list box of a combo box. 
Syntax dwReturned = SendMessage (HWND hControl, CB_GETCURSEL, WORD wParam, DWORD 
lParam) | 
Returns - DWORD. The index of the Suen selected item in the list box. Returns CB_ERR if no item is. 
selected. 
Parameters 
hControl HWND: The window handle of the combo box control. 
wParam . WORD: Not used. Set equal to 0. 
lParam DWORD: Not used. Set equal to OL. 
~CB_GETDROPPEDCONTROLRECT OWin2.0 OWin30 mWin31 
Purpose — Retrieves the screen coordinates of the list box of a combo box in the dropped-down position. | 
Syntax dwReturned = SendMessage (HWND hControl, CB_GETDROPPEDCONTROLRECT, WORD 
- wParam, DWORD lParam) 
Returns DWORD, always equal to CB_OKAY. 
Parameters Pe eo. 
hControl HWND: The window handle of the combo box control. 
wParam: WORD: Not used. Set equal to 0. 


lParam ___. __ DWORD: A pointer to a RECT data structure that will hold the screen soar diaies of the combo 
box drop-down list box when SendMessage() returns. 


Related Messages CB_GETITEMHEIGHT |. | | . a 


CB_GETEDITSEL | OWin20 mWind0 mWin3l 
Purpose _ _ Returns the range of characters selected within the edit control of the combo box. 

Syntax dwReturned = SendMessage (HWND hControl, CB_GETEDITSEL, WORD wParam, DWORD 

lParam) 

Returns DWORD. The low-order word contains the starting position and the high-order word has the end- 
; ing ve of the characters selected. Rebar CB_ERR onerror. | 

Parameters: | 

hControt a ae HWND: The window handle of the combo oe control. 

wParam . WORD: Not used. Set equal to0.. - 

lParam - DWORD: Not used. Set equal to OL. 

CB_GETEXTENDEDUI O Win 2.0 OWin 3 0 mw Win 3.1 
" Purpose Determines if a combo box has the default or extended user interface. 

Syntax dwReturned = pondhessage (HWND. hControl, CB -GETEXTENDEDUI, WORD orarim; 

DWORD lParam) 
Returns. DWORD. TRUE if the combo box has an extended user interace, FALSE if not. 
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Parameters 

hControl HWND: The window handle of the combo box control. 

wParam _ WORD: Not used. Set equal to 0. 

lParam DWORD: Not used. Set equal to OL. 

Related Messages CB_SETEXTENDEDUI 

Comments The extended user interface for a combo box is set by sending the CB_SETEXTENDEDUI mes- 
sage to the combo box control. The control must have either the CBS_DROPDOWN or 

CBS_DROPDOWNLIST style. The extended style has the following effects: 

~ Clicking the static text field at the top causes the list box to be displayed (CBS_. DROPDOWNLIST 
style only). 

Pressing the (PcoN) key displays the list box. . 

The top static text field cannot be scrolled if the list box is rit visible. 
CB_GETITEMDATA - OWin2.0 gWin30 sWindl . 
Purpose Retrieves the 32-bit value associated with an item in an owner-redrawn combo box. 

Syntax dwReturned = bere (HWND hControl, CB_GETITEMDATA, WORD wParam, DWORD 

lParam) 

Returns . DWORD, the 82 bit value. Returns CB_ERR on error. 

Parameters . 

hControl HWND: The window handle of the combo box control. 

wParam WORD: The index of the item. The first item is 0. 

lParam — DWORD: Not used. Set equal to OL. 

CB_GETITEMHEIGHT OWin2.0 OWin3d.0 mWin31 

Purpose — Determines the height of an item in a combo box control. , ‘ 

Syntax dwReturned = SendMessage (HWND hControl, CB_GETITEMHEIGHT, WORD wParam, 

os DWORD lParam) 

Returns © DWORD, the height of the item in pixels. 

Parameters . 

hControl HWND: The window handle of the combo box control. 

wParam WORD: Set to —1 to determine the height of the top edit (or static text) control at the top of the 
combo box. Set to 0 if the combo box does not have the CBS_OWNERDRAWVARIABLE style. The — 
height of items in the list box will be returned. © 

If the list box has the CBS_OWNERDRAWVARIABLE style, set wParam to the index of the 
item for which the height should be determined. This will normally be repeated for several items 
; in the list box. 

[Param _  DWORD: Not used. Set equal to OL. 

Related Messages CB_SETITEMHEIGHT, WM_DRAWITEM = 

CB_GETLBTEXT | OWin2.0 e@Win30 eg Win3l 

Purpose _ Retrieves the string held in an item in the list box of a combo box. 

Syntax dwReturned = SendMessage (HWND hControl, CB_LGETLBTEXT, WORD wParam, DWORD 
lParam) 


Returns DWORD, the length of the string in bytes. Returns CB_ERR on error. 
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If the combo box is owner-redrawn, but it does not have the CBS_HASSTRINGS style, the 
buffer pointed to by Param will receive the 32- bit value associated with the item. 


Parameters 
hControl HWND: The window handle of the combo box control. 
wParam _ WORD: Contains the index of the list box item. The first item is 0. 
lParam DWORD: A pointer to a character buffer to hold the string retrieved. Use CB_GETLBTEXTLEN to 
retrieve the length of the string. Be sure to include an extra character in the buffer for the termi- 
nating NULL character. 
CB_GETLBTEXTLEN OWin2.0 mWin30 | Win3.l 
Purpose Finds the number of characters in a string in the list box of a combo box. 
Syntax -  dwReturned = SendMessage (HWND hControl, CB_GETLBTEXTLEN, WORD wParam, DWORD 
_ [Param) 
Returns DWORD, the length of the string in bytes. Returns CB_ERR on error. 
Parameters . 
hControl HWND: The window handle of the combo box control. 
wParam | WORD: Contains the index of the string. The first item is 0. 
lParam DWORD: Not used. Set equal to OL. 
CB_INSERTSTRING OWin20 mWin30 mWin3.l 
Purpose _ Adds a new string or 32-bit item to the list box of a combo box. 
Syntax dwReturned = sensed’ (HWND hControl, CB_INSERTSTRING, WORD wParam, DWORD 
. lParam) 
Returns : DWORD, the index of the inserted item. Returns CB _ERRSPACE if there is not enough memory 
. for the item. Returns CB_ERR for all other errors. 
Parameters 
hControl HWND: The window handle of the combo box control. 
wParam . WORD: Contains the index position to insert the string. 0 for the first item, 1 for the second, etc. 


Use —1 for the last. All items below the insertion point will have new index values, one greater 
than their index prior to the insertion. 


lParam > - DWORD: A pointer to a null-terminated character string to be added. If the combo box has the 
es " owner-redrawn style, /Param holds the 32-bit value to set for the item. 


CB_LIMITTEXT . : — OWin20 wWind0 mWindl 
Purpose Sets the maximum number of characters that a user can enter in the edit control of the combo box. 
Syntax dwReturned = SendMessage ene hControl, CB_LIMITTEXT, WORD wParam, DWORD 
_ (Param) 
Returns DWORD, nonzero oe the limit was set, zero if not. 
Parameters 
- hControl HWND: The window handle of the combo box control. 
wParam WORD: The maximum number of characters for the edit control. 
lParam DWORD: Not.used. Set t equal to OL. 
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CB_RESETCONTENT , OWint0 wWinkd0 Wind! 


Purpose Removes all elements from the list box of a combo box, and frees memory associated with the 
items. 

Syntax dwReturned = SendMessage caWND hControl, CB_LRESETCONTENT, WORD wParam, 
DWORD lParam) 

Returns DWORD, not used. 

Parameters 

hControl HWND: The window handle of the combo box control. 

wParam - WORD: Not Used. Set. equal to 0. 

lParam DWORD: Not Used. Set equal to OL. 


If the combo box is owner-redrawn, but does not have the CBS_HASSTRINGS style, the owner 
of the combo box will receive a WM_DELETEITEM message for each item in the combo box. - 


CB_SELECTSTRING oWin20 mWin80 wWindl 


Purpose Finds a matching string in the combo box list and displays it in the edit control of the combo box. 
If the combo box has the owner-redrawn style, the match is based on comparing 32-bit values. 

Syntax dwReturned = SendMessage (HWND hControl, CB_SELECTSTRING, WORD wParam, DWORD 

lParam) 

Returns - DWORD, the index of the string found. Returns CB_ERR if no match was found. In this case, the 
edit control is not changed. 

Parameters 

hControl HWND: The window handle of the combo box control. - 

wParam WORD: The list box item number before the first item to be searched. The search wraps around to 


the beginning if no match is found between the starting point and the end of the list. 
You can find duplicate entries in the list by repeatedly using the last index as the starting 
point for the next search. 


lParam ~ DWORD: A pointer to the character string to match. The string in the list box of the oui box 
can be longer, as long as the first characters match the string pointed to by Param. If the combo 
box has the owner-redrawn style, Param contains the 32-bit value to match. 


CB_SETCURSEL OWin2.0 wWind0 Wind! 


Purpose Selects and highlights an item in the list box of a combo box. If the item is not visible, the list is 
scrolled into view. The edit control of the combo box is changed te reflect the selection. Any 
highlighting of the previous selection is removed. 


Syntax  dwReturned = SendMessage (HWND hControl, CB_SETCURSEL, WORD rare DWORD 
: lParam) 
Returns DWORD. Normally not used. Set to CB_ERR on error, such as an out of range Pari value, 
Parameters 
hControl HWND: The window handle of the combo box control. 
-wParam . WORD: The index of the item to select. Set wParam to —1 to deselect all items. 


lParam DWORD: Not used. Set equal to OL. 
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CB_SETEDITSEL | OWin20 mWin30 mwin3l 
Purpose Selects a range of characters in the edit control of a combo box. . 
Syntax dwReturned = SendMessage (HWND hControl, CB _ SETEDITSEL, WORD wParam, DWORD 
aa lParam) 
Returns DWORD, TRUE if successful, FALSE if not. 
Parameters £5 
hControl.~ HWND: The window handle of the combo box control. 
. wParam WORD: Not used. Set equal to 0. | 
[Param — _DWORD: The low-order word contains the starting character position. The high-order word con- 
. tains the ending position. 
Soe NES a ee 
Purpose Selects either the default or extended user interface for a combo box. 
Syntax dwReturned = SendMessage (HWND hControl, CB_LSETEXTENDEDUI, WORD wParam, 
DWORD lParam) — 
Returns’ DWORD, CB_OK if successful, CB_ERR on error. 
Parameters | es cons 
~ -hControl HWND: The window handle of the combo box control. 
wParam WORD: Set to TRUE to use the extended user interface. Set to FALSE to use the default user 
interface. 
lParam DWORD: Not used. Set equal to OL. 
Related Messages CB_GETEXTENDEDUI 
Comments The extended user interface for a combo bag is set by sending the CB_SETEXTENDEDUI mes- 
sage to the combo box control. The control must have either the CBS_DROPDOWN or. 
CBS_DROPDOWNLIST style. The extended style has the following effects: 
Clicking the static text field at the top causes a list box to be ee ey DROPDOWNLIST 
style only). 
Pressing the (Gon) key displays the list box. . 

- The top static text field cannot be scrolled if the list box is not visible. 
CB_SETITEMDATA | OWin2.0 wWind0 eWind.l 
Purpose Changes the 32-bit value associated with a list box item of a combo box created with the owner- 

redrawn style. 
Syntax. dwReturned =  SendMessage (HWND hControl, CB _ SETITEMDATA, WORD wParam, DWORD, 
oe .. lParam) 
Returns DWORD. Normally not used. CB_ERR on error. 
Parameters 
‘ hControl HWND: The window handle of the combo box control. 
. wParam WORD: ‘The index number of the item in the list box. 
lParam DWORD: The new 32-bit value to set. . 
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~ CB_ SETITEMHEIGHT : OWin2.0 OWin30 sWindl 
Purpose Sets the height of either the top edit control or list box items in a combo box control. 

. Syntax — dwReturned = SendMessage (HWND hControl, CB_ SETITEMHEIGHT, WORD wParam, 

DWORD /Param) 

Returns DWORD, CB_ERR on error. 
Parameters 
hControl HWND: The window handle of the combo box control. : 
wParam WORD: Set to —1 to change the height of the top edit (or static text) control at the top of the 


combo box. Set to 0 if uhe combo box does not have the CBS_OWNERDRAWVARIABLE style. The 
height of every item in the list box will be changed. If the list box has the CBS_OWNERDRAWVARIABLE 
Style, set wParam to the index of the item for which the height should be changed. The ait item 
has an index of zero. 


[Param DWORD: Set equal to the height in pixels for the item to be changed. 
Related Messages CB_GETITEMHEIGHT, CB_SETITEMDATA, WM_DRAWITEM 


CB_SHOWDROPDOWN OWin2.0 gWin3.0  mWin3t 

” Purpose Shows or hides the drop-down list box of a combo box created with the CBS_ DROPDOWN or 
CBS_DROPDOWNLIST style. . 

Syntax ' SendMessage (HWND hControl, CB_SHOWDROPDOWN, WORD wParam, DWORD lParam) 

Parameters , ' 

hControl HWND: The window handle of the combo box control. 

wParam, WORD: TRUE to display the list box, FALSE to hide it. 

[Param DWORD: Not used. Set equal to OL. 


Combo Box Notification Codes Summary 


When the user makes a selection within a combo box or edits the top edit window, Windows notifies the parent 

window with a WM_COMMAND message. The combo box ID is passed as wParam, while the combo box handle is the 

low-order word of /Param. The specific notification code, such as CBN_DBLCLK, is the high-order word of [Param. 
_Table 9-7 summarizes the notification codes. 


CBN_DBLCLK Notifcation that thet user fe ‘double-cicksd an item in the list bi of the combo box. 
CBN_DROPDOWN Notification that the list box portion of a combo box is about to be made visible. 
CBN_EDITCHANGE The string in the edit control of the combo box has been changed. 

CBN_EDITUPDATE Notification that Windows is about to change the text in the edit control of a combo box. 
CBN_ERRSPACE Notification that Windows has run out of memory room to add another item to acombo box. . 
CBN_KILLFOCUS Notification that the combo box has lost the input focus. 

CBN_SELCHANGE Notification that the current selection in the list box part of the combo box has changed. 
CBN_SETFOCUS Notification that a combo box has the input focus. 


Table 9-7. Combo Box Notification Codes. 
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Combo Box Notification Codes Descripuons 


CBN. DBLCLK : sm Win2.0 esWin3.0 Win3.l 

Panpase Notification that the user has double-clicked an item in the list box of the combo box. Use 
CB _GETCURSEL to determine which item was selected. This message will only be sent if the list 
box of the combo box is always visible(CBS_SIMPLE style). For drop-down list boxes, the first 
mouse click causes the selection to be made and causes the list box to be pulled up. . 


Syntax Returned as part of a WM_COMMAND message, ee by the program’s message processing 
Mey function (WndProc()). 
Parameters - 
wParam: WORD: Contains the ID value for the combo box. This is the integer value eet for the hMenu 
_. parameter when CreateWindow() was called. 
lParam . DWORD: The low-order word contains the window handle of the combo box. The high-order word 
| . contains CBN_DBLCLK. 
CBN_DROPDOWN BWin20 mWin3s0 Wind 
Purpose Notification that the list box portion of a combo box is about to be made visible. This will not 
cour if the combo box was created with the CBS_SIMPLE style which always shows the list box. 
Syntax Returned as part of aWM_COMMAND message, peace by the program’s message processing 
Cae function (WndProc()). 
Parameters | - 
wParam WORD: Contains the ID value for the combo box. This is the integer value set for the hMenu 
parameter when CreateWindow() was called. 
lParam DWORD: The low-order word contains the window handle of the combo box. The high-order word 
contains CBN_DROPDOWN. 
CBN_EDITCHANGE | gWin2.0 wWin30 wWin3l 
Purpose Notification that the string in the edit control of the combo box has been changed. This message 
Bs ' is received after the change has been made. 
Syntax ‘Returned as part of a WM_COMMAND message, proceed oe the program’s message processing 
. . function (WndProc()). 
Parameters | 
wParam WORD: Contains the ID value for the combo box. nus is the integer value set for the hMenu 
parameter when CreateWindow() was called. 
lParam DWORD: The low-order word contains the window handle of the combo box. The mentee word 
contains CBN_EDITCHANGE. 
CBN_EDITUPDATE : Win2.0 mWin30 gmWin31 
Purpose _ Notification that Windows is about to change the text in the edit control of a combo box. : 
Syntax — Returned as part of a WM_COMMAND message, processed by the program’s message processing 
~ function rae): 
Parameters 
wParam WORD: Contains the ID value for the éainbo box. This i is the integer value set for the hMenu 


parameter when CreateWindow() was s called. 
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lParam DWORD: The low-order word contains the window handle of the combo box. ane ey order word 
contains CBN_EDITUPDATE. . 5 
CBN_ERRSPACE _ gWin20 oWin30 Wind 
Purpose Notification that Windows has run out of memory to add another item to a combo box. 
Syntax Returned/as part of a WM_COMMAND message, processed by the program’s message processing 
function (WndProc()). | 
Parameters 
wParam WORD: Contains the ID value for the combo box. This is the integer value set for the hMenu 
| : parameter when CreateWindow() was called. 
lParam DWORD: The low-order word contains the window handle of the combo box. The high-order word 
contains CBN_ERRSPACE. 
CBN _ KILLFOCUS | OWin2.0 oWin30 wWin3l 
Purpose Notification that the combo box has lost the input focus. _ 
Syntax Returned as part of a WM_COMMAND message, processed by the program’s message processing 
function (WndProc()). 
Parameters : 
wParam WORD: Contains the ID value for the combo box. This is the integer value set for the hMenu 
parameter when CreateWindow() was called. 
lParam DWORD: The low-order word contains the window handle of the combo box. The high-order aid 


contains CBN_KILLFOCUS. 


CBN_SELCHANGE “= oWin20 oWin30 mWindl 
_ Purpose - Notification that the current selection in the list box part of the combo box has changed. This can 
: be due to either selecting a new item in the list box or through typing text in the edit control. 
Syntax Returned as part of a WM_COMMAND message, processed by the program’s message processing 
function (WndProc()). 
Parameters 
wParam WORD: Contains the ID value for the combo box. This is the integer value set us the hMenu 
parameter when CreateWindow() was called. 
lParam DWORD: The low-order word contains the window handle of the combo box. The high-order word 
contains CBN_SELCHANGE. — 
CBN_SETFOCUS | oWin2.0 oOWin30 Wind! 
Purpose — Notification that a combo box has the input focus. Keyboard input will show up in the edit control. 
Syntax -Returned as part of a WM_COMMAND message, processed by the program’s mesiee Process 
function (WndProc()). 
Parameters 
wParam _ WORD: Contains the ID value for the combo box. This is the integer value set for the hMenu 
parameter when CreateWindow() was called. - 
‘lParam DWORD: The low-order word contains the window handle of the combo box. The high-order word: 


contains CBN_SETFOCUS. 
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Dialog Box Window iMeasagee 


The only two messages that are specific to the dialog box window itself are DM_GETDEFID and DM_ SETDEFID. 
These functions get and change the push button ID number for the default pushbutton. This is the pushbutton that 
will be activated if the user hits the key. The WM_NEXTDLGCTL message allows the default pushbutton con- 
trol to be changed. This message is sent with PostMessage(), not SendMessage(), to avoid having the change occur 
while other messages are being processed. (WM_NEXTDLGCTL is documented in the last section of this chapter, due 
to the WM prefix.) 

The controls in a dialog box, such as buttons and list boxes, are all child window controls. They can be manipu- 
lated by sending the control messages. The SendDlgItemMessage() function is usually more convenient than 
SendMessage() for dealing with dialog box controls. Chapter 13, Dialog Boxes, has a full discussion of dialog box 
controls. 


DM GETDEFID. Wingo mWing0) Wing 


Purpose Retrieves the ID value of the default pushbutton in a dialog box. The default pushbutton is the . 
- button that will be pressed if the user hits the key right after the dialog box appears. 
Syntax dwReturned = SendMessage (HWND hControl, DM_GETDEFID, WORD wParam, DWORD 
= lParam) 
Returns DWORD. The low-order word contains the button’s ID value. The high- order word contains 
. DM_GETDEFID. Returns NULL on error. 
Parameters 
hControl - HWND: The window handle of the dialog box. 
wParam WORD: Not used. Set equal to 0. 
Param’ DWORD: Not used. Set equal to OL. 
DM DM_SETDEFID eWin2.0 mWin30 eaWin3.l 
Purpose’ Changes the ID value of the default ishibitton control in a dialog box. The default pushbutton is 
the button that will be pressed if the user hits the Enter) key right after the dialog box appears. 
Syntax dwReturned = SendMessage (HWND hControl, DM_SETDEFID, WORD wParam, DWORD 
lParam) 
Returns DWORD, not used. 
Parameters 
hControl HWND: The window handle of the dialog box. 
wParam ‘WORD: The ID value of the default pushbutton. 
lParam DWORD: Not used. Set equal to OL. 
Edit Control Messages . 


Edit controls are most frequently used for single lines of input. Typically, the user is given a place to enter a file name, 
or some other short character string. These uses just scratch the surface as to what is possible with edit controls. 
Windows has a lot of basic word processing functions built into edit controls. Any time your program uses an edit 
control, you automatically get editing functions such as the ability to select text using the mouse, delete selected text 
with the key, use the cursor keys and the key, etc. Edit controls can be as big as the entire client area 
of a window, and they can be combined with scroll bars to produce scrollable editing areas. 

You will probably find that edit controls give you all the power you need for text input in your programs. Edit controls 
do not allow text formatting, as is needed in word processing, and they can become cumbersome if you need to add a lot of 
new functionality. However, you may find that the edit controls allow you to prototype a program quickly. 
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Figure 9-5 shows a multiline edit control placed as a 
child window in an application. The edit control style in- 
cludes the WS_VSCROLL style, which adds a vertical 
scroll bar to the edit control. After several lines of text eres 
are typed, the user can scroll through the text using the This is a bunch of 

scroll bar. Typing in the edit area automatically wraps to lines in an edit 
the next line when a word exceeds the width of the edit 
area, and automatically scrolls up when the bottom is 
reached. ire 

In this example, when the user clicks the “Do It!” 
menu item, the program logic recovers the string data 
entered and shows it at the bottom of the screen. This is 
abit more complex than it might be,as Windows doesnot 
automatically keep the entered text asanull-terminated Figure 9. 5. A Multiline Edit Control.- 
string (no null at the end is maintained). The program 
must add the length of each of the lines to find the end of the string. This is a small nuisance, considering how much 
“instant word processing” the program gains by just using an edit control. 

Listing 9-5 shows the WndProc() function of the program that creates the edit control. The edit control is built 
when the program receives the WM_CREATE message. The example allocates a separate local memory area to store 
the string data. Windows automatically enlarges this area to make room for added text. Note that PostMessage() is 
used with the EM_SETHANDLE message to establish the link between the string memory area and the edit control. 
SendMessage() also could have been used to transmit the message to Windows. 

Allocating a separate memory area for the edit control’s string data is not always necessary. Windows will main-- 
tain a default text area if the edit control is inside a dialog box created with the DS_LOCALEDIT style. This is 

_ convenient with dialog boxes, as the program can also use the SetDlgItemText(), SetDlgItemInt(), GetDigItemText(), 
and GetDlgItemInt() functions for quick ways to fetch and set the text string inside of edit controls, These functions 
are explained in Chapter 13, Dialog Boxes. This technique is not used i in the example i in Listing 9-5, as the edit control 
is a child window and is not in a dialog box. 

Retrieving the text from the memory buffer is simply a matter of obtaining the handle to the memory area. The 
program must determine the length of the complete string, including all of the lines in the multiline edit control. This 
requires adding the length of each line’s string. When the total length is known, the program adds the ip CeraRIAENg 
‘NULL character and displays the string at the bottom of the screen. 


& Listing 9-5. Creating a Multiline Edit Control 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


static HWND hEdit ; 

HDC hdc ; 

static HANDLE hEditText ; 

PSTR s ptzText ; 

int i, nTextLen, nTotatLen, nLines, nIndex ; 

switch (iMessage) , /* process windows messages */ 
{ 


case WM_CREATE: 
hEdit = CreateWindow (“EDIT", “", 
WS_CHILD | WS_VISIBLE | ES_AUTOVSCROLL | ES_MULTILINE 
| ES_LEFT | ES_NOHIDESEL | WS_BORDER | WS_VSCROLL, 
10, 10, 150, 100, hWnd, NULL, ghinstance, NULL) ; 
ShowWindow ChEdit, SW_SHOW) ; 


hEditText = LocalAlloc (LMEM_MOVEABLE, 30) ; /* edit buffer */ 
ptzText = bocalbork ChEditText) ;/* null byte for first char */ 
*ptzText = 0 ; /* in edit buffer to begin */ 


LocalFree ChEditTeRED = 
/* attach edit buffer to edit control */ 
PostMessage ChEdit, EM_SETHANDLE, hEditText, OL) ; 
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break 
case WM_COMMAND /* process menu items */ 
switch (WParam) 
{ 
case IDM_DOIT: /* pull the text out and display it */ 
ptzText = LocalLock (hEditText) ; 
nLines = SendMessage (hEdit, EM_GETLINECOUNT, 0, OL) ; 
nTotalLen =O; 
for (i = 0; i <nLines ; i++) /* find string length */ 
° { 
nIndex = SendMessage (hEdit, EM_LINEINDEX, 
i, OL) ; 
nTextLen = SendMessage ChEdit, EN_LINELENGTH, 
: nIndex, OL) ; 
nTotalLen +t=.nTextLen ; 
} 
*(ptzText + nTotalLen) = 0 ; /* null terminate string */ 
hoC = GetDC (hWnd) ; 
TextOut (hDC, 10, 130, ptzText, lstrlen (ptzText)) ; 
ReleaseDC (hWnd, hDC) ; 
LocalUntock ChEditText) ; 
break ; oo, 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 


default: 


+, 
return (OL) ; 
} 


LocalFree ChEditText) ; 
PostQuitMessage (0) ; 
break ; . 
/* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


"Windows has several undocumented messages, including EM_GETTHUMB and EM_SETFRONT, that are defined 
in the WINDOWS.H file that deal with edit controls. The adventurous reader can experiment with these at his or her 


own risk. There is no guarante 


e that undocumented messages will be continued in future versions of Windows. 


Edit Control Message Summary 


Table 9-8 summarizes the edit 


EM_CANUNDO 


EM_EMPTYUNDOBUFFER 
EM_FMTLINES 


EM_GETHANDLE 
EM_GETUNE 


EM_GETLINECOUNT 
EM_GETMODIFY 
EM_GETRECT 
EM_GETSEL 
EM_UMITTEXT 


control messages. The detailed message descriptions are in the next section. 


a0 


Determines if an edit control can correctly process EM_UNDO messages to undo the effect ofa 
change. — ; 


Clears the undo buffer that Windows installs for an edit control to handle WM_UNDO messages. 


Used with multiline edit controls to add or remove CR LF character sequences at the end of 
each line. ; 


Returns a handle to the memory area the edit control is using to store the string data. 


Copies.a line from the edit control into a memory buffer. This message is only processed by 
multiline edit controls. 


Determines the number of text lines in a multiline edit control. 

Determines if the text in the edit control has been changed by the user. 

Returns the bounding rectangle for the formatting area of an edit control. 

Returns the starting and ending character positions of the edit text selected by the user. 
Restricts the length of the text string a user may enter into an edit control. 
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EM_LINEFROMCHAR 
EM_LINEINDEX 


EM_UINELENGTH 
EM_LINESCROLL 
EM_REPLACESEL 
EM_SETHANDLE 
EM_SETMODIFY 
EM_SETPASSWORDCHAR 


EM_SETRECT 
EM_SETRECTNP 
EM_SETSEL 
EM_SETTABSTOPS 
EM_SETWORDBREAK 
EM_UNDO 
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_ Returns the line number of the selected text or of a given character position in an edit control. 


Returns the character position in the complete string contained in a multiline edit control for the 
start cf a line. 


_ Retums the number of characters in a line of a multiine edit control. 


Scrolls an edit control horizontally cr vertically. 

Replaces the currently selected text with new text. 

Links the edit control to a memory buffer to hold the edit text. 

Sets the modify flag for the edit control. 

Allows you to change from an asterisk (*) to any desired character placeholder for the password 
style. 

Sets the inner formatting rectangle of the edit control. The text is repainted. 

Sets the irmer formatting rectangle of the edit contrcl. The text is not repainted. 

Selects all of the characters in a given range. 

Sets the positions of the tab stops in a multiline edit control. 

This message sets a new word break function. 

Copies the text from the delete buffer back into the edit control at the insertion point (the caret 


location). 


Table 9-8, Edit Control Message Summary. 


In addition to the EM edit control messages, there are four messages that deal with cut and paste operations for 
selected text within the edit control area. The messages allow to be copied the selected text between the edit control 
and the clipboard. These messages are summarized in Table 9-9. The full documentation of these messages is in the 
ois part of this oe in the Windows oe seseait a as these messages start with hes bilo 


WM_CLEAR Deletes the seiecied | text in an nec control without copying it to the ipboecd 
WM_COPY Copies selected text within an edit control to the clipboard. 

WM_CUT 2 Copies the current selected text from an edit control to the clipboard. 
WM_PASTE Copies the text from the clipboard into an edit control. 


Table 9-9, Additional Edit Control Messages. 


Edit Control Message Descriptions | 


EM_CANUNDO 
Purpose 


Win2.0 gWin3.0 Win 3.1 


Determines if an edit control can correctly process EM_UNDO messages to undo the effect of a: - 
change. If the undo buffer size was exceeded, the change cannot be correctly undone. 


Syntax dwReturned = SendMessage (HWND hControl, EM_CANUNDO, WORD wParam, DWORD 
lParam) 

Returns — DWORD. TRUE if the edit control can undo changes, FALSE if not. 

Parameters : 

hControl HWND: The window handle of the child window edit control 

wParam WORD: Not used. Set equal to 0. 

lParam DWORD: Not used. Set equal to OL. 
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EM_EMPTYUNDOBUFFER OWin2.0 e8Win30 mWin3l 

Purpose Clears the undo buffer that Windows installs for an edit control to handle WM_UNDO messages. 
The edit buffer is automatically emptied if the edit control receives a: WM_ SETTEXT c or 
EM_SETHANDLE message. 


Syntax SendMessage (HWND hControl, EM_ EMPTYUNDOBUFFER, WORD WEAEEM; DWORD 
iParam) 

Parameters 

hControl HWND: The window handle of the child window edit control. 

wParam WORD: Not used. Set equal to 0. 

lParam DWORD: Not used. Set equal to OL. 

EM_FMTLINES Win2.0 mWin3.0 mWin3l 

Purpose Used with multiine edit controls to add or remove'CR CR LF character sequences a the end of 


each line (0x0D, 0x0D, 0x0A hexadecimal). The line ends where the string word wraps can be 
marked with these three bytes, which is different from a “hard return,” when the user has pressed 
the key. Normally, multiline edit controls are stored as one long string, without control 
characters where the string wordwraps. An exception is text in which the user has hit the 
key. This will add two bytes, CR and LF, to the string. These CR LF pairs are not affected by the 
EM_FMTLINES message. Note that the string size will change. Use EM_LINELENGTH to find the 


new length of each line. 
Syntax dwReturned = SendMessage (HWND hControl, EM_FMTLINES, WORD wParam, DWORD 
. lParam) 
Returns ~ DWORD. Nonzero if formatting occurs, otherwise zero. 
Parameters 
hControl HWND: The window handle of the child window edit control. 
wParam WORD: Nonzero to place CR CR LF character sequences at the end of each wordwrapped line. 
Zero to remove them. 
lParam DWORD: Not used. Set equal to OL. 
_EM_GETHANDLE mWin20 -mWin3.0 _mWin3. 
Purpose Returns a handle to the memory area the edit control is using to store the string data. Use 
: EM_SETHANDLE to link a memory handle to an edit control. 
Syntax dwkReturned = SendMessage (HWND hControl, EM_GETHANDLE, WORD wParam, DWORD 
: lParam). 
Returns DWORD, the data handle of the memory buffer that holds the edit string. 
Parameters 
hControl HWND: The window handle of the child window edit control. 
wParam WORD: Not used. Set equal to 0. 
lParam | DWORD: Not used. Set equal to OL. 
Comments Allocating a separate memory area for the edit control’s string data is not always necessary. 


Windows will maintain a default text area if the edit control is inside a dialog box created with 
the DS_LOCALEDIT style. This is convenient with dialog boxes, as the program can also use the 
SetDigitemText(), SetDigltemInt(), GetDlgItemText(), and GetDigItemInt() functions for quick 
ways to fetch and set the text string inside of edit controls. These functions are explained in 
Chapter 13, Dialog Boxes. 
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EM_GETLINE : eWin2.0 eWin30 eWin3l 


Purpose Copies a line from the edit control into a memory buffer. This message is only processed by 
: multiline edit controls. Use EM_GETHANDLE to retrieve a handle to the memory area used to 
store the string of a single line edit control, or for the entire contents of a multiline edit control. 


Syntax . dwReturned = SendMessage (HWND hControl, EM_GETLINE, WORD wParam, DWORD 
7 lParam) 
Returns DWORD, the number of characters copied. 
Parameters 
~ hControl HWND: The window handle of the child window edit control. e 
wParam WORD: The line number to copy. 0 is the first line. 
lParam DWORD: A pointer to the memory buffer that will contain the copied string. Set the first WORD 


of the buffer equal to the maximum number of characters to copy (as an integer). This value will 

. be read before the copy operation begins to ensure that the buffer size is not exceeded. The 
copied line is not null-terminated. The text copied to the buffer pointed to by Param will not 
automatically be null-terminated. 


Pad 


EM_GETLINECOUNT BWin2.0 @Win3d.0 wWin3.1 

Purpose _ Finds out the number of text lines in a multiline edit conal Single line edit controls do not 
respond to this message. 

Syntax dwReturned = SendMessage (HWND hControl, EM_GETLINECOUNT, WORD wParam, 
DWORD lParam) 

Returns DWORD. The number of lines in the multiline edit control. 

_ Parameters 

hControl HWND: The window handle of the child window edit control. 

wParam WORD: Not used. Set equal to 0. 

lParam DWORD: N«t used. Set equal to OL. 

EM_GETMODIFY BWin2.0 mWin3.0 mWin3.1 

Purpose Determines whether or not the text in the edit control has been changed by the user. — 

Syntax dwReturned = SendMessage (HWND hControl, EM_GETMODIFY, WORD wParam, DWORD | 
lParam) 

Returns DWORD, nonzero if the edit text has been changed, zero if not. 

Parameters 

hControl HWND: The window handle of the child edit yindow control. 

wParam WORD: Not used. Set equal to 0. 

lParam DWORD: Not used. Set equal to OL. 

EM _GETRECT OWin2.0 8Win30 esWin31 

Purpose Returns the bounding rectangle for the formatting area of an edit control. The size of this rect- 
angle can be changed with the EM_SETRECT command: _ 

Syntax oe (HWND hControl, EM_GETRECT, WORD wParam, DWORD lParam) 

Parameters 

hControl HWND: The window handle of the child window edit control. 

wParam WORD: Not used. Set equal to 0. 
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lParam DWORD: A ‘bitter to a RECT data structure. The four elements of this structure will be set after 
—— the message has been processed. Client coordinates are used. 

EM_GETSEL . G Win 2.0 eWin3.0 e&Win3.1 

Purpose Returns the starting and fending character positions of the edit text selected by the user. Text is 


selected within the edit control by dragging the mouse pointer over one or more characters. The 
selected text is highlighted automatically. 


Syntax dwReturned = SendMessage (HWND hControl, EM _GETSEL, WORD uParam, DWORD 
5 lParam) 
Returns DWORD. The low-order word contains the first selected duntidier position. The high-order word 
contains the ostiion of the first character after the selection. ; 
Parameters 
hControl -__ HWND: The window handle of the child window edit control. 
wParam WORD: Not used. Set equal to 0. 
lParam - DWORD: Not used. Set equal to OL. 
"EM. LIMITTEXT | gg Win2.0) og Win3.0) sw Win3.l 
Purpose Restricts the length of the text string a user may enter into an edit control. If the user attempts to 
exceed this limit, the system beep and no additional characters can be added to the edit area until 
some are deleted. EM_LIMITTEXT does not limit the length of text that can be inserted using 
EM_SETHANDLE. It does not affect the size of the memory buffer used to store the characters. 
Syntax SendMessage (HWND hControl, EM_LIMITTEXT, WORD wParam, DWORD [Param) © 
Parameters 
hControl HWND: The window handle of the child window edit control. . 
wParam WORD: The maximum number of characters to allow in the edit control. Set to 0 to remove any 
limit (other than available memory). 
Param DWORD: Not used. Set equal to OL. 
| EM_LINEFROMCHAR | nWin20 mWind0 mWin3l 
Purpose Returns the line number of the selected text or of a given character position in an edit control. 
Syntax dwReturned = SendMessage (HWND hControl, EM_LINEFROMCHAR, WORD wParam, 
DWORD lParam) 
Returns ~  DWORD, the line number. 
Parameters 
hControl HWND: The window handle of the child window edit control. 
wParam WORD: Set either to —1 to retrieve the line number of the start of the text block the user ids 
selected, or set to a positive integer to specify a character position in the complete edit string. 
lParam - DWORD: Not used. Set equal to OL. 
EM _LINEINDEX ; eWin20 mWin30 mWin3t 
Purpose Returns the character position in the coniplete string contained in a multiline edit control for the 


start of a line. This is the number of characters in the edit control’s memory buffer before the 
start of the line. This value is used in processing EM_LINELENGTH messages. The message can 
also be used to find the location of the edit caret within the edit control. The edit caret is acti- 
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vated when the user clicks the mouse within the edit area. It can be moved using the mouse, 
arrow keys, or key. 


Syntax dwReturned = SendMessage (HWND hControl, BM_LINEINDEX, WORD wParam, DWORD 
lParam) 

Returns DWORD, the number of characters in the edit control's memory buffer before. the start of the 

given jin: 

Parameters 7 

hControl HWND: The window handle of the child window edit control. 

wParam WORD: The line number. Alternatively, if set equal to -1, the message returns the index of the 
character position of the edit caret within the edit control. 

lParam DWORD: Not used. Set equal to OL. 

EM_LINELENGTH raWin2.0 mWin3.0 mWin31 

Purpose Returns the number of characters (bytes) in a line of a multiline edit control. 

Syntax dwReturned = SendMessage (HWND hControl, EM_LINELENGTH, WORD wParam, DWORD 
lParam) 

Returns DWORD, the length of the line. 

Parameters 

hControl HWND: The window handle of the child window edit control. . 

wParam ~ WORD: Specifies the character position of the start of the line. Use EM_LINEINDEX to find this 


value for a given line number. If wParam is set equal to —1, the position of the edit caret is 
returned. If wParam is set equal to -1 and a group of characters has been selected (highlighted 
in the edit control); the returned value is the character number of the first character in the first 


line of the selection. 
lParam DWORD: Not used. Set equal to.0L. 
EM_LINESCROLL Win2.0 wWin3.0 wWin3.1 
Purpose Scrolls an edit control horizontally or vertically. None of the text is lost, even though a portion 
_ May be obscured after the scrolling operation. 
Syntax ' SendMessage (HWND hControl, EM_LINESCROLL, WORD wParam, DWORD lParam) 
Parameters r 
hControl - HWND: The window handle of the child window edit control. Se 
- wParam WORD: Not used. Set equal to 0. 
lParam DWORD: Set the low-order word equal to the number of lines to scroll vertically, and set the high- 


order word equal to the number of character positions to scroll horizontally. Positive values scroll 
down and right, negative values scroll up and left. 


EM_REPLACESEL | | oWin2.0 sWin30 es Win3l 


Purpose Replaces the currently selected text with new text. The selected text is highlighted in the edit 
area by dragging the mouse cursor over a range of characters. 

Syntax SendMessage (HWND hControl, EM_REPLACESEL, WORD wParam, DWORD lParam) 
Parameters 

hControl HWND: The window handle of the child window edit control. 


wParam WORD: Not used. Set equal to 0. 
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Param | DWORD: A pointer to a null-terminated string containing the new string to replace the selected 


text. The edit control string length may change after this replacement. 
EM_SETHANDLE Win2.0 &Win30 &8Win3d!) 
Purpose Links the edit control to a memory buffer to hold the edit text. The buffer must be a local handle 
; (data in the application’s data segment). This buffer is automatically resized as needed to hold 
new input text. : 
Syntax SendMessage (HWND hControl, EM_SETHANDLE, WORD wParam, DWORD lParam) 
Parameters 
hControl | HWND: The window handle of the child window edit control. 
wParam WORD: Contains the handle to the memory buffer. Use LocalAlloc() to create the memory area. 
~ lParam DWORD: Not used. Set equal to OL. 
Notes: © 2 More than one buffer can be linked to one edit control at different times. This is a way to switch 


between different default strings, without destroying either buffer when the switch is made. If the 
edit control is in a dialog box, this message can only be accepted if the dialog box was created with 
the DS_LOCALEDIT style. Otherwise, the dialog box uses its own memory area for the edit string. 


EM_SETMODIFY Win2.0 mWin3.0 Win. 

Purpose Sets the modify flag for the edit control. This message is handy if you need to repaint the text, and 
the program uses the EM_GETMODIFY message to check if painting is necessary. 

Syntax SendMessage (HWND hControl, EM_SETMODIFY, WORD wParam, DWORD lParam) 

Parameters a 

hControl HWND: The window handle of the child window control. 

wParam - WORD: TRUE for modified, FALSE for not. 

lParam DWORD: Not used. Set equal to 0L. 

EM_SETPASSWORDCHAR ; OWin2.0 e&Win3.0. me Win3l 

‘Purpose The abilities to have an edit control with the ES_PASSWORD style is new with the 3.0 version of 


Windows. By default, a password edit control shows every typed letter as an asterisk (*), even — | 


though the edit control’s buffer contains the characters as typed. EM _SETPASSWORDCHAR al- 
lows you to change from the asterisk to any desired character placeholder. 


Syntax SendMessage (HWND hControl, EM_SETPASSWORDCHAR, WORD wParam, DWORD lParam) 


Parameters : if 

hControl HWND: The window handle of the child window edit control. 

wParam WORD: The character to be displayed in place of the input letters. If hControl is NULL, the typed 

letters are displayed as is, removing the password style effects. 

lParam DWORD: Not used. Set equal to OL. 

EM_SETRECT _ _oWin20 oWin30  eWindl 

Purpose . Sets the inner formatting rectangle of the edit control. Any text in the edit control is reformatted 
\ and repainted to fit within the bounds of the reotanel: This message will not mre for single line 

eh ' edit controls. 
ee SendMessage (HWND hControl, EM _SETRECT, WORD wParam, DWORD Para) 
Parameters 


hControl i. HWND: The window handle of the child window edit contro. 
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wParam WORD: Not used. Set equal to 0. 

lParam DWORD: A pointer to a RECT data structure holding the dimensions of the formatting rectangle — 
in client coortnales 

EM_SETRECTNP BWin2.0 mWin3.0 wmWin3.1 

Purpose Sets the inner formatting rectangle of the edit control. Any text in the edit control is reformatted 


to fit within the bounds of the rectangle. The text is not automatically repainted. Otherwise, it is 
the same as EM_SETRECT. This message will not work for single line edit controls. 


Syntax SendMessage (HWND hControl, BM_SETRECTNP, WORD wParam, DWORD lParam) 
Parameters . 

hCentrol HWND: The window handle of the child window control. 

wParam WORD: Not used. Set equal to 0. 

lParam DWORD: A pointer to a RECT data structure holding the dimensions of the formatting rectangle 


in client coordinates. 


EM_SETSEL | m@Win2.0 “mWin30 mWin3.! 
Purpose _ Selects all of the characters in a given range. The selected characters are highlighted i in reverse 
video. 
‘Syntax SendMessage (HWND hControl, EM_SETSEL, WORD wParam, DWORD lParam) 
- Parameters 
hControl HWND: The window handle of the child window edit control. 
wParam WORD: Not used. Set equal to 0. 
lParam DWORD: The starting character position in the low-order word and the ending character position 


in the high-order word. These positions are in the complete edit string, not in an individual line. 
Selecting a position beyond the end of the string selects the character up to, and including the 
last character in the string. You can use the MAKELONG macro to specify a range for Param. For 
example, MAKELONG(20,3) would specify the characters from position 3 to 20 in the edit string. 


EM_SETTABSTOPS OWin2.0 mWin30 mf Win3.1 
Purpose Sets the positions of the tab stops in a multiline edit control. 
Syntax dwReturned = SendMessage (HWND hControl, EM_SETTABSTOPS, WORD wParam, DWORD 
lParam) ng 
Returns DWORD. Nonzero if the tabs were set, zero on error. ie 
Parameters 
hControl HWND: The window handle of the child window control. 
wParam | WORD: The number of tab stops that will be set. 
lParam DWORD: A pointer to an integer array containing the tab stops. The tab stops are raghsiivedlt in dialog 
units (1/4 of a character width). The tab stops must be in ascending order, as illustrated here. 
e int nTab C3] = (20, 40, 68) ; 
Notes If wParam is zero and lParam is NULL, the tab stops default to every 32 dialog units (8 charac- 
ters). IfwParam is one, nen the tab stops will be uniformly spaced at a distance specified in the 
lParam value. 
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EM SETWORDBREAK | | | mWin20 mWing0 Win 


Purpose Sets a new word break function. Word break functions determine how a string should be split 
when it does not fit on one line of a: multiline edit control. The default word break function proaks 
lines at space characters. 


Syntax SendMessage (HWND hControl, EM_SETWORDBREAK, WORD wParam, DWORD [Param) 


Parameters 

hControl HWND: The window handle of the child window control. 

wParam’, . WORD: Not used. Set equal to 0. 

iParam DWORD: The procedure-instance address of the word break function. Use MakeProcInstance() 


to create the procedure-instance. The word break function must be listed in the EXPORTS sec- 
tion of the program’s .DEF definition file. The callback function for doing word breaks should 
have the following format: 


LPSTR FAR PASCAL WordBreakFunc (LPSTR IpchEditTeat, short ichCurrentWord, short 
cchEditTect) ; 


UpchEditText : _ LPSTR: A pointer to the text in the edit control. 
ichCurrentWord . Short: The point at which the function should start checking for needed word wrapping. 


cchEditText Short: The number of character positions in the edit text. 
Returns The function should return a pointer to the first letter of the next word in the edit buffer. If the 
current word is the last word in the text, the return value should point to the first byte after the 
last word. 
EM_UNDO | mWin2.0  mWin30 mWin3.l 
Purpose Windows maintains a character buffer to hold the last group of characters selected, deleted, and 


changed. The buffer expands to hold the selection, limited only by the capacity of the local seg- 
ment storage. This command copies the text from the delete buffer back into the edit control at 
the insertion point (the caret location). 


- Syntax _ dwReturned = SendMessage (HWND hControl, BM_UNDO, WORD wParam, DWORD lParam) 


_ Returns DWORD. Nonzero if successful, zero on error. 
Parameters 
hControl =~ ~——~XHWND: The window handle of the child window edit control. 
wParam =, WORD: Not used. Set equal to 0. 
lParam eee Not used. Set equal to OL. 


- Edit Control Notification Messages 

Normally, you will not need to process EN_ notification messages (see the list in Table 9- -10) in your program. The 
_ editing functions in the edit control are so complete that little intervention is needed. If you want to chauge the: 
default behavior of the edit control, you can intercept the notification messages. For example, you might want to 
increase the size of an-edit control to fit added text. The EN_CHANGE and EN_UPDATE messages provide warning 
that text has beer or will be modified. Edit notification messages are sent to the parent window of the edit control as 
_ WM_COMMAND messages. The edit control's ID value is passed as the wParam value with WM_COMMAND The edit 
Conmrors window handle is the low-order vo of lParam, while the dibiaas sigHneauons code is the cosdselin word. 


EN.CHANGE Notification that the user has changed text within the sitostial 
EN_ERRSPACE Notification that the edit control has run out of memory space in the local memory area. 
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EN_HSCROLL Notification that the user has clicked an edit control’s horizontal scroll bar. 

EN_KILLFOCUS Notifi cation that the edit control has lost the input focus. 

EN_MAXTEXT Notifi cation that the user has attempted to insert more characters than will ft in in an edit control. 
EN_SETFOCUS —_Notification that an edit control has obtained the input focus. 

EN_UPDATE Notification that an edit control is about to display text changed by the user. 

EN_VSCROLL Notification that the user has clicked the vertical scroll bar of a multiline edit control. 


Table 9-10. Edit Control Notification Message Summary. 


Edit Control Message Descriptions 


EN _ CHANGE mWin2.0 mWin3.0 mWin3.1 

Purpose Notification that the user has changed text within the edit control. This message is sent after the 
display is updated. Use EN_UPDATE to receive notification before the change is shown on the 
display. 

Syntax Returned as part of a WM_COMMAND message, processed by the program’s message processing 
function (WndProc()). 

Parameters 

wParam - WORD: Contains the ID value for the edit control. This is the integer value set for the hMenu 


parameter when CreateWindow() was called. 


lParam DWORD: Contains the window handle for the edit control in the low-order word. Contains 
EN_CHANGE in the high-order word. 


EN_ERRSPACE | mWin2.0 mWin30 mWin3.1 


Purpose Notification that the edit control has run out tof memory space in the local memory area. 

Syntax Returned as part of aWM_COMMAND message, processed by the program’s message processing 
. function (WndProc()). 

Parameters 

wParam WORD: Contains the ID value for the edit control. This is the integer value set for the hMenu 


parameter when CreateWindow() was called. 


lParam DWORD: Contains the window handle for the edit control in the low-order word. Contains © 
EN_ERRSPACE in the high-order word. 


EN_ HSCROLL : _ mWin2.0 mWin3.0 mWin31_ 
Purpose — Notification that theu user has clicked the edit control’s horizontal scroll bar. This is only possible 
if the edit control was created with the WS_HSCROLL style. 
Syntax Returned as part ofa WM_COMMAND message, processed by the program’s message processing 
; oe (WndProc()). 
Parameters 
wParam WORD: Contains the ID value for the edit control. asst is the integer value set for the hMenu 


parameter when -CreateWindow() was called. 


lParam DWORD: Contains the window handle for the edit control i in the ike ‘edet ery Contains 
. EN HSCROLL i in the ne order word. 
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EN_KILLFOCUS | | BWin2.0 mWin30. Win 3. 1 


Purpose Notification that the edit control is lost the input focus. If some input is necessary before con- 

tinuing, you may want to intercept this code, show a warning, and then use SetFocus() to return 

the focus to the edit control. If you use this type of logic, always provide the user an escape route, 
such as hitting the (Ese) key. 


Syntax Returned as part of a WM_COMMAND message, provessed hy the program: S message processing 
: function (WndProc()). 
Parameters 
wParam WORD: Contains the ID value for the edit control. This is the integer value set for the hMfenu 
parameter when CreateWindow() was called. 
lParam DWORD: Contains the window handle for the edit control in the low- ering word. Contains 
EN_KILLFOCUS in the high-order word. : 
EN_MAXTEXT rae 4 OWin2.0 wm Win3.0 Win 3.1 
Purpose Notification that the user attempted to insert more characters than will fit in an edit control. Notifi- 
cation code will only be sent if the edit control was created without the ES | AUTOHSCROLL style. 
Syntax - Returned as part of a WM_COMMAND message, processed by the program’s message processing 
~~ “function (WndProc()). 
Parameters 
wParam ° - WORD: Contains the ID value for the edit control. This is the integer value set for the hMenu 
parameter when CreateWindow() was called. 
[Param - DWORD: Contains the window handle for the edit control in the low-order word. Contains 


EN_MAXTEXT in the high-order word. 


EN_SETFOCUS , : ow Win20 mw Win38.0 gw Win3.) 

Purpose ' Notification that.an edit control has obtained the input focus. Keyboard input will then show up 
inside the edit control. 

Syntax | Returned as part of a WM_COMMAND message, processed by the program’s message processing 
function (WndProc()). Fass 

Parameters | be ond : . ih 

wParam | WORD: Contains the ID value for the edit control. This is the integer value set for the hMenu — 

parameter when CreateWindow() was called. 

lParam DWORD: Contains the window handle for the edit control in the low- aide: word. Contains 
EN_SETFOCUS in the high-order word. 

EN_UPDATE ss fe mWin2.0 mWin3.0 Wind] 

Purpose Notification that an edit control is about to display text changed by the user. This is sent after the 


changes have been made to the character data in the edit control’s memory buffer, but before the 
: changes are displayed. A common use of this message is to allow resizing of an edit control if 
necessary to fit added text. 


Syntax Returned as part of aWM_COMMAND message, processed by the program’s message processing 
ae om bs function (WndProc()). 

Parameters 

wParam _ WORD: Contains the ID value for the edit control. This is i integer value set for the hMenu 


parameter when CreateWindow() was called. - 
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lParam DWORD: Contains the window handle for the edit ee in the low-order word. Contains 
EN_UPDATE in the high-order word. 


EN_VSCROLL mWin2.0 mWin3.0 mWin3l 


‘Purpose Notification that the user has clicked the vertical scroll bar of an edit control. This will only occur 
if the edit control was created with the WS_VSCROLL style. An example of this style of edit 
control is given in this chapter at the beginning of the discussion on edit control messages. 


Syntax ~ Returned as part of a WM_COMMAND message, processed by the program’s message processing 
function (WndProc()). . 

Parameters 

wParam WORD: Contains the ID value for the edit contro]. This is the integer value set for the hMenu 


parameter when CreateWindow() was called. 


lParam DWORD: Contains the window handle for the edit control in the low-order word. Contains 
EN_VSCROLL in the high-order word. 


List Box Messages 


List boxes can be thought of as a subset of combo boxes. Most of the functions are 
the same, although list boxes have a few more formatting options. List boxes lack 
the edit control at the top and do not “drop down.” That is, list boxes are always 
visible. When designing an application, you will want to use list boxes in situations 
where the user will usually select an item. If the user will most often leave the 4 [TeSEEEERPPSPr EEE 
selection as is, but needs to be reminded of which item is selected,a combo boxis § 
more appropriate. Combo boxes take up less space in their “rolled up” form, so you 
can make a complex dialog box or child window look less cluttered with combo 
boxes. 

Figure 9-6 shows an example of a list box. This one is sical as it was created 
with a title bar using the WS_CAPTION style. This means that the list boxcanbe Figure 9-6. A List Box 
moved around on the screen like a typical child window. If you want a title, butdo Control. 
not want a moveable list box, surround a normal list box (without the WS_CAPTION 
style) with a button group control. Group controls have titles, but are not moveable. 

Note that the list box includes a scroll bar on the right side. The standard list box style LBS_STANDARD is the 
combination of LBS_NOTIFY | LBS_SORT ! WS_VSCROLL | WS_BORDER. The vertical scroll bar is visible only if the 
number of items in the scroll bar exceeds the size of the formatting area. The notify style is critical, as it instructs the 
list box to send a WM_COMMAND message when the user selects an item. Another interesting thing about the list box 

in Figure 9-6 is that the text inside includes tab characters. List boxes can have tab stops set at any location, accurate 
to within a quarter of a character width. This can be a convenient way to display small database tables. 

~ Listing 9-6 shows the WndProc() function that creates the list box in Figure 9-6, Note that the LBS_HASSTRINGS 
style is used, so that the control uses its default near memory buffer to hold the strings. The LBS_USETABSTOPS style 
is also specified. The list box has the text items added to it when the user clicks the “Do It!” menu item. Three tab 
stops are set using the LB_SETTABSTOPS message. LB_SETTABS STOPS transmits a pointer to the array nTabs// 
that contains the tab positions as integers. The tab positions are computed based on dialog box units, one quarter of 
a character width per unit. 

Because the LBS_NOTIFY style was set (as part of LBS_STANDARD), the scroll bar sends a WM_COMMAND 
message, with wParam set to the list box ID value, when the user selects a list item with the mouse. In this example, 
the program retrieves the text from the list box and displays it below the list box using the TabbedTextOut() function. 
TabbedTextOut() has the nice feature of using the same convention for tab stops as the list box, so the output text 
looks right. ; 


4 The selected text is: 
p More Inserted Text 
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© Listing 9-6. List Box Control 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ . 

static HWND hListBox ; 


HWND _ hPicked ; 

HDC | hdc ; 

int nSel ; 

char cBuf (301 ; ; 

static int ntabs [3] = (32, 56, 72} ; 

switch (iMessage) ; /* process windows messages */ 
{ 


case WM_CREATE: 
hListBox = CreateWindow ("LISTBOX", “List Box", 
WS_CHILD | WS_VISIBLE | LBS_HASSTRINGS | LBS_STANDARD 
| LBS_USETABSTOPS | WS_CAPTION, 
10, 10, 180, 80, hWnd, 100, ghInstance, NULL) ; 
ShowWindow (hListBox, SW_SHOW) ; 
_ break ; 
case WM_COMMAND: -/* process menu items and controls */ 


switch (wParam) 

{ 

case 100: ; /* List box id value */ 
hPicked = LOWORD (lParam) ; 
if CHIWORD (lParam) == LBN_SELCHANGE) 


{ 
hDC = GetDC (hWnd) ; : 
nSel = (WORD) SendMessage (hListBox, 
LB_GETCURSEL, O, OL) ; 
SendMessage (hListBox, LB_GETTEXT, nSel, 
“(CDWORD) CLPSTR) cBuf) ; 
TextOut (hDC, 10, 120, 
"The selected text is:", 21) ; 
TabbedTextOut (hDC, 10, 140, cBuf, 
strlen (cBuf), 3, (LPINT) nTabs, 0) ; 
ReleaseDC (hWnd, hDC) ; 
} 
break ; 


case IDM_DOIT: 
SendMessage (hListBox, LB_RESETCONTENT, 0, OL) ; 
SendMessage (hListBox, LB_SETTABSTOPS, 3, 
CDWORD)CLPINT) nTabs) ; 
SendMessage (hListBox, LB_ADDSTRING, 0, 
CDWORD) C(LPSTR) "First \tString") ; 
SendMessage (hListBox, LB_ADDSTRING, 0, 
_ CDWORD) CLPSTR) “Second \tString"™) ; 
SendMessage (hListBox, LB_ADDSTRING, 0, 
CDWORD) CLPSTR) “Last \tString"™) ;. 
SendMessage (hListBox, LB_INSERTSTRING, 2, 
CDWORD) CLPSTR) “Inserted \tText") ; 
SendMessage (hListBox, LBLINSERTSTRING, 2, 
CDWORD) CLPSTR) “More \tInserted \tText") ; 


break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
; break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
; PostQuitMessage (0) ; 
break ; . eas 
default: ee /* default windows message processing */ 
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return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
} 
return (OL) ; 


from alist. The methods and messages used exactly match those used for owner-redra’ combo box items. Review the 
section on combo boxes for an example that uses these powerful features. 


List boxes can also use owner-redrawn list entries. Using them is handy for an a color or bitmap pattern 
Table 9-11 summarizes 8 the list box mesons The detailed message descriptions are in the tohowing section. 


LB_ADDSTRING Adds an item to a list box. 


LB_DELETESTRING Deletes an item from the list box. 

LB_DIR Fills the list box with file names from a directory search. 

LB_FINDSTRING Locates the first string in the list box that matches a given set of starting characters. 
LB_GETCARETINDEX Determines which item in a list box has the focus. (Win 3.1) 

LB_GETCOUNT Returns the number of items in the list box. 

LB_GETCURSEL Finds the index number of the currently selected item in the list box. 
LB_GETHORIZONTALEXTENT Finds the width in pixels that a scroll bar can be scrolled horizontally. 

LB_GETITEMDATA Retrieves the 32-bit value associated with an item in an owner-redrawn list box. 
LB_GETITEMHEIGHT Determines the height of an item in a list box. (Win 3.1) 

LB_GETITEMRECT Retrieves the dimensions of the rectangle that bounds an item as currently displayed in a list box. 
LB_GETSEL Finds out if an item in a list box has been selected. 

LB_GETSELCOUNT Retums the total number of items selected in multiple-selection list box. 
LB_GETSELITEMS Fills an array of integers with the item numbers of the selections in a multiple- -selection list box. 
LB_GETTEXT Retrieves the string held in an item in the list box. 

LB_GETTEXTLEN Finds the number of characters in a string in the list box. 

LB_GETTOPINDEX Returns the index number of the top visible item in a list box. 

LB_INSERTSTRING Adds a new string or 32-bit item to the list box. 

LB_RESETCONTENT Removes all elements from the list box and frees memory associated with the items. 
LB_SELECTSTRING Finds a matching string in the list box and highlights it. 

LB_SELITEMRANGE Selects or deselects one or more consecutive items from a multiple selection list box. 
LB_SETCARETINDEX Sets which item in a multipie-selection list box has the focus rectangle. (Win 3.1) 
LB_SETCOLUMNWIDTH - Sets the width in pixels for the columns in a multi-column list box. 

LB_SETCURSEL Selects and highlights an item in a list box. 

LB_SETHORIZONTALEXTENT — Sets the width in pixels that a list box can be scrolled horizontally. 

LB_SETITEMDATA Changes the 32-bit value associated with a list box created with the owner-redrawn style. 
LB_SETITEMHEIGHT Changes the height of items in an owner-redrawn list box. (Win 3.1) 

LB_SETSEL Selects an item in a multiple-selection list box. 
LB_SETTABSTOPS ‘Sets the position of the tab stops to use when displaying items inside of the list box. 
LB_SETTOPINDEX Scrolls a list box so as to make a specified item the top visible item. 


Table 9-11. List Box Message Summary. 
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List Box Message ‘Samimary” 


One other message worth knowing about is WM_SETREDRAW. This message allows the list box to be temporarily 
inhibited from redrawing the contents as additions and subtractions are made. WM_SETREDRAW speeds up the 
redrawing of the contents and reduces the distracting.“flicker” of different items being displayed one at a time. 
(WM_SETREDRAW is documented at the end of this chapter because of its WM prefix.) 


List Box Message Descriptions 


LB_ADDSTRING : mWin20 mWind0 Wind 


Purpose 


Adds an item (usually a character string) to a list box. If the list box has the LBS_SORT style, the 
string is placed in the list and the list re-sorted. Otherwise, the string is added to the end of the 
list. If the list box is owner-redrawn, but it was created without the LBS_ HASSTRINGS aaa) the 
inserted item is a 32-bit value. 


Syntax © dwReturned = SendMessage (HWND hControl, LB_ADDSTRING, WORD wParam, DWORD 
lParam) 

Returns DWORD. The returned value is the index of the new entry in the list box. Returns LB_LERRSPACE 
if there is not enough memory to store the value. Returns LB_ERR on any other error. 

Parameters 

hControl HWND: The window handle of the list box control. 

wParam WORD: Not used. Set to 0. 

lParam DWORD: For list boxes with the LBS_HASSTRING style, /Param contains a ea to a null- 

terminated string for a text item. For other styles, [Param encodes a 82-bit value for the item. 

This value can be retrieved when processing WM_DRAWITEM messages as the ztemData element 
of the DRAWITEMSTRUCT structure passed with the message. See the example in the section on 
owner-redrawn combo boxes for more details. 

LB_DELETESTRING Win2.0 wWin30 wWin31— 

Purpose Deletes an item from the list box. 

-- Syntax dwReturned = Sendmlesaee (HWND hControl, LB_DELETESTRING, WORD wParam, DWORD 

iParam) 

Returns DWORD. The number of items remaining i in the list. Returns LB__ ERR ifwParam is not avalid list 

element index. . 

Parameters 

hControl HWND: The window handle of the list box control. 

wParam WORD: Contains the index to the list element. 0 for the first iten:. 

[Param DWORD: Not used. Set to OL. 

LB_DIR * gWin2.0 sWin3.0 Wind] 

Purpose Fills the list box with file names from a directory search. 

Syntax dwReturned = SendMessage (HWND hControl, LB_DIR, WORD wParam, DWORD lParam) 

Returns DWORD. The number of items displayed minus 1. Returns LB_ERRSPACE if there is not enough 

_ memory for the list. Returns LB_ERR for any other error. 
Parameters a . 
hControl HWND: The window handle of the list box control. 
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wParam WORD: Contains the DOS file attribute value. The values can be combined by using the C lan- 
guage binary OR operator (1). The attributes are listed in Table 9-12. 


0x0000 Read/write data files with no other attributes set (normal files). 


0x0001 Read-only files. 
0x0002 Hidden files. 
_ 0x0004 System files. 
0x0010 Subdirectories. 
0x0020 Archived files. 
0x2000 LB_DIR flag. Places messages associated with filling the list bux on the applications message queue, rather 
than sending them directly. 
0x4000 Drives. : 
0x8000 Exclusive bit. If this is set, only the specified file attribute type is recovered. If not set, normal files are 


. displayed in addition to the types listed. 


Table 9-12. File Attribute Flags. 


lParam DWORD: A pointer to a file search specification string (like “*.*” or “*.TXT”). The string can 
contain a full pathname specification. 


LB_FINDSTRING OWin2.0 mWin3d.0 mWin31 

Purpose Locates the first string in the list box that matches a given set of starting characters. Alterna- 
tively, finds the list box item matching a 32-bit value for an owner-drawn list box. 

Syntax dwReturned = SendMessage (HWND hControl, LB_FINDSTRING, WORD ESE, DWORD 
lParam) 

Returns DWORD. The index of the first string in the list box that starts with the characters in the string 

pointed to by /Param. Returns LB_ERR (—1) if the search did not find a match. 

Parameters 

hControl HWND: The window handle of the list box control. 

wParam WORD: The index of the list box item before the first item to start the search. The search will 
wrap around if the end of the list is passed without a match. Set wParam = -1 to search the 
entire list. You can find multiple occurrences of a matching string by repeatedly ue this mes- 
sage and each time starting from the previous match. 

lParam DWORD: A pointer to a null-terminated string. The characters in this string must all be matched 
by the beginning of an item in the list to have a match. 

Note: This message will also match 32-bit values if the list box is an owner-drawn control, created 
without the LBS_HASSTRINGS style. In this case, (Param holds the 32-bit value to match. 

LB_GETCARETINDEX OWin2.0 OWin30 mWin31 

Purpose | Determines which item in a list box has the focus. 

Syntax dwReturned = SendMessage (HWND hControl, LB_GETCARETINDEX, WORD wParam, 
DWORD lParam) 

Returns DWORD, the index of the item that has the focus. Ina single-selection list box, this is the selected 


item. In a multiple-selection list box, this is the selection that has the focus rectangle. 
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Parameters 

hControl HWND: The window handle of the list box control. 
wParam WORD: Not used. Set equal to 0. 

lParam DWORD: Not used. Set equal to OL. 


Related Messages LB_SETCARETINDEX, LB_GETCURSEL 


LB_GETCOUNT mWin2.0 mWin30 mWin3.1 
Purpose Returns the number of items in the list box. . 
Syntax dwReturned = SendMessage (HWND hControl, LB_GETCOUNT, WORD wParam, DWORD 
lParam) 
Returns DWORD. The number of items in the list box. Returns LB_ERR on error. 
Parameters ; 
hControl ‘ HWND: The window handle of the list box control. 
wParam WORD: Not used. Set equal to 0. 
lParam . DWORD: Not used. Set equal to OL. 
LB_GETCURSEL mWin2.0 m@Win30 mWin3.1 
Purpose Finds the index number of the currently selected item in the list box. 
Syntax dwReturned = SendMessage (HWND hControl, LB_GETCURSEL, WORD wParam, DWORD 
a lParam) 
Returns DWORD. The index of the currently selected item in the list box. Returns LB_ERR if no item is 
selected. 
Parameters . 
hControl HWND: The window handle of the list box control. 
wParam WORD: Not used. Set equal to 0. 
lParam DWORD: Not used. Set equal to OL. 
LB_GETHORIZONTALEXTENT OWin2.0 mWin3.0 mWin3.1 
Purpose Finds the width in pixels that a scroll bar can be scrolled horizontally. The list box must have - 
been defined with the WS_HSCROLL style to respond to this message. 
Syntax dwketurned = SendMessage (HWND hControl, LB_GETHORIZONTALEXTENT, WORD 
wParam, DWORD [Param) 
Returns | ‘DWORD. The scrollable width of the list box, measured in pixels. 
Parameters . 
hControl HWND: The window handle of the list box control. 
wParam .. WORD: Not used. Set equal to 0. 
lParam DWORD: :Not used. Set equal to OL. 
LB_GETITEMDATA | — oWin20  mWin3.0 mw Win3.l 
Purpose Retrieves the 32-bit value associated with an item in an owner-redrawn list box: 
Syntax . dwReturned = SendMessage (HWND hControl, LB_GETITEMDATA, WORD wParam, DWORD 
_ lParam) 
Returns DWORD, the 32- bit value. Returns LB_ ERR on error. 
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Parameters 


hControl HWND: The window handle of the list box control. 

wParam WORD: The index of the item. The first item is 0. 

lParam DWORD: Not used. Set equal to OL. 

LB_GETITEMHEIGHT OWin2.0 OWin3.0 sWin3.1 

Purpose Determines the height of an item in a list box. 

Syntax dwReturned = SendMessage (HWND hControl, LB _GETITEMHEIGHT, WORD Spice 
DWORD lParam) 

Returns DWORD, the item’s height in pixels. Returns LB_ERR on error. 

Parameters 

hControl HWND: The window handle of the list box control. 

wParam WORD: Set equal to the index of an element in the list box if the list box has the LBS_OWNER- 


DRAWVARIABLE style. The first item has an index of zero. Otherwise set it equal to zero, as all 
elements will have the same height. 


lParam DWORD: Not used. Set equal to OL. 
Related Messages LB_SETITEMHEIGHT, LB_SETITEMDATA, WM_DRAWITEM 


LB_GETITEMRECT OWin2.0 mWin3.0 mWin3.1 

Purpose Retrieves the dimensions of the rectangle that bounds an item currently displayed in a list box. 
This is used with owner-redrawn list boxes with the LBS_OWNERDRAWVARIABLE style. 

Syntax dwReturned = mencMessaee (HWND hConirol, LB_GETITEMRECT, WORD wParam, DWORD 

; lParam) 

Returns DWORD, normally ignored. Returns LB_ERR on error. 

Parameters 

hControl — HWND: The window handle of the list box control. 

wParam WORD: The index of the item. The first item is 0. 

lParam DWORD: Contains a far pointer to a RECT structure. The structure receives the bounding rect- 


angle data after the message is processed. Client coordinates are used. 


LB -GETSEL | sm Win2.0 mm Win38.0) sm Win3.1 

Purpose Finds out if an item in a list box has been selected. 

Syntax dwReturned = SendMessage (HWND hControl, LB_GETSEL, WORD wParam, DWORD /Param) 

Returns DWORD, greater than zero if selected, zero if not selected. Returns LB_ERR on error. 

Parameters | 

hControl HWND: The window handle of the list box control. 

wParam WORD: The index ofthe item. The first item is 0. 

lParam DWORD: Not used. Set-equai to OL. 

LB_GETSELCOUNT | OWin2.0 mWin3.0 mWin31 

Purpose — Returns the total number of items selected in a multiple-selection list box. The list box must have 
been created with the LBS_MUTIPLESEL style to have more than one item selected. 

Syntax dwReturned = sia ai un hControl, LB_GETSELCOUNT, WORD wParam, DWORD 
lParam) . 
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Returns DWORD, the number of selected items. Returns LB _ERR on error ( for example, Senile this 
message to a list box avithourt the LBS_MULTIPLESEL style). 
Parameters 
hControl HWND: The window handle of the list box Ciel 
wParam WORD: Not used. Set equal to 0. 
lParam DWORD: Not used. Set equal to OL. 
LB_GETSELITEMS OWin2.0 mWin3.0 ms Win31 
Purpose Fills an array of integers with the item numbers of the selections in a multiple-selection list box. 
The list box must have been created with the LBS_MUTIPLESEL style to have more than one 
item selected. 
Syntax dwReturned = SendMessage (HWND ia LB_GETSELITEMS, WORD wParam, DWORD 
lParam) 
Returns DWORD, the number of items put in the array. Returns LB_ERR on error, (for example sending 
this message to a list box without the LBS_MULTIPLESEL style). 
Parameters 
hControl HWND: The window handle of the list box control. 
wParam WORD: The maximum number of selection items that will fit into the integer array. 
Param DWORD: A far pointer to an array of integers. Make sure that there are at least as many elements 
in the array as the maximum specified by wParam to avoid overwriting past the end of the array ’ 
- memory area. , . 
LB_GETTEXT aWin20 eWin30 mWin3.l 
Purpose Retrieves the string held in an item in the list box. 
Syntax dwReturned = SendMessage (HWND hControl, LB_ GETTEXT, WORD wParam, DWORD 
lParam) 
Returns DWORD, the length of the string in bytes. Returns LB_ERR on error. 
Parameters 8 
hControl HWND: The window handle of the list box control. . 
wParam WORD: Contains the index of the list box item. The first item is 0. 
lParam DWORD: A pointer to a character buffer that holds the string retrieved. Use LB_GETTEXTLEN to 
Cy i retrieve the length of the string. Add one to this value for the terminating NULL character. 
Note: _ his message will also retrieve the 32-bit value associated with an item in an owner-redrawn list 
, box. ; 
LB_GETTEXTLEN mWin2.0 eWin30 3 mWin31 
Purpose Finds the number of characters in a string in the list box.. 
Syntax dwReturned = SendMessage (HWND hControl, LB_GETTEXTLEN, WORD wParam, DWORD 
lParam) 
Returns — DWORD, the length of the string in bytes, excluding the terminating NULL charactor: Retuens 
LB_ERR on error. ak 
- Parameters 


hControl HWND: The window handle of the list box control: 
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wParam WORD: Contains the index of the string. The first item is 0. 
[Param DWORD: Not used. Set equal to OL. 
LB_GETTOPINDEX Win2.0 mWin3.0 mWin3.1 
Purpose Returns the index number of the top visible item in a list box. This will be greater than 0 if the list 
box has been scrolled. 
Syntax dwReturned = SendMessage (HWND hControl, LB_GETTOPINDEX, WORD wParam, DWORD 
lParam) 
Returns DWORD, normally ignored. Returns LB_ERR on error. 
Parameters 
hControl HWND: The window handle of the list box control. 
wParam WORD: Not used. Set equal to 0. 
lParam | DWORD: Not used. Set equal to OL. 
LB_INSERTSTRING mw Win2.0 mWin30 @ Win 3.1 
Purpose Adds a-new string or 32-bit item to the list box. 
Syntax dwReturned = SendMessage (HWND hControl, LB_INSERTSTRING, WORD wParam, DWORD 
lParam) 
Returns DWORD, the index of the inserted item. Returns LB_ERRSPACE if there is not enough memory 
for the item. Returns LB_ERR for all other errors. 
Parameters 
hControl HWND: The window handle of the list box control. 
wParam WORD: Contains the index position of the location to insert the string. 0 for the first item, 1 for 
the second, etc. Use ~1 for the last. All items below the insertion point will have new index values. 
[Param DWORD: A pointer to a null-terminated character string to be added. If the list box has the 
owner-redrawn style, Param holds the 32-bit value to set for the item. 
LB_RESETCONTENT BWin2.0 mWin30 mWin31 
Purpose Removes all elements from the list box and frees the memory associated with the items. 
Syntax dwReturned = SendMessage (HWND hControl, LB_LRESETCONTENT, WORD eee 
DWORD /Param) 
Parameters 
hControl HWND: The window handle of the list box control. 
wParam WORD: Not used. Set equal to 0. 
lParam DWORD:. Not used. Set equal to OL.. 
_LB_SELECTSTRING | eWin2.0 wWin30 mWin3l 
Purpose Finds a matching string in the list box and highlights it. If the list box has the owner- redrawn 
: style, the match is based on comparing 32-bit values. 
Syntax dwReturned = ees ov hControl, LB -SELECTSTRING, WORD wParam, DWORD. 
lParam) 
Returns DWORD, the index of the string found. Returns LB_ERR if no match was found. 
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' Parameters 
hControl HWND: The window handle of the list box control. . 

- wParam WORD: The list bex item number before the first item to be searched. The search wraps around to 
the beginning if no match is found between the starting point and the end of the list. You can find 
duplicate entries in the list by repeatedly using the last index as the starting point for the next 
search. 

lParam DWORD: A pointer to the character string to match. The string in the list box can be longer, as 
; long as the first characters match the string pointed to by /Param. If the list box has the owner- 
redrawn style, but it does not have the LBS_! pee nnes style, Param contains the 32-bit value 
to match. , 
LB_SELITEMRANGE | | OWin2.0 mWin3.0 mWin31 
Purpose - Selects or deselects one or more consecutive items from a multiple-selection list box. The list box 
; must have been created with the LBS_MUTIPLESEL style to have more than one item selected. _ 
Syntax =. dwketurned= SendMessage aaa hControl, LB_SELITEMRANGE, WORD wParam, Aa 
.  [Param) c 
Parameters 
hControl HWND: The window handle of the list box control. 
wParam WORD: TRUE to select items, FALSE to deselect them. 
lParam '  DWORD: The low-order word contains the index of the first item to select. The high-order word 
contains the index of the last item to select. If both values are the same, only one item is selected. 
LB_SETCARETINDEX | — oWin.0 OWin3.0 mm Win31 
Purpose Sets which item in a multiple-selection list box has the focus rectangle. If the item is not visible, 
it is scrolled into view. 
Syntax . dwketurned = SendMessage (HWND hControl,. LB _SETCARETINDEX, WORD wParam, 
DWORD lParam) 
Returns DWORD, returns LB_ERR on error. 
Parameters 
hControl HWND: The window handle of the list box control. 
wParam. WORD: The index of the list box item which should receive the focus. Zero for tne first item. 
lParam DWORD: Not used. Set equal to OL. 


Related Messages LB_GETCARETINDEX, LB_SETCURSEL 


LB_SETCOLUMNWIDTH OWin20 OWin30 mWin3.l 
Purpose __ Sets the width, in pixels, for the columns in a multicolumn list box. The list box must have been 
| |), ¢reated with the LBS_MULTICOLUMN style to use this message. 

Syntax © || dwReturned = SendMessage (HWND hControl, LB_SETCOLUMNWIDTR, WORD wParam, 
. DWORD /Param) 

Parameters . . 

hControl ©  HWND: The window handle of the list box control. 

wParam ~ WORD: The width, in pixels, to set every column. All columns must have the same width. 

lParam _. .DWORD: Not used. Set equal to OL. - : 
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LB_SETCURSEL . OWin2.0-. mWin3.0 mWin3.l 


Purpose Selects and highlights an item in a list box. If the item is not visible, the list is scrolled into view. 

* Any highlighting of the previous selection is removed. This message should be used with single- 

selection list boxes (the standard style), not multiple-selection ones. For the eniter use 
LB_SELITEMRANGE. 


Syntax dwReturned = SendMessage (HWND hControl, LB_LSETCURSEL, WORD wParam, DWORD 


lParam) 
Returns DWORD. Normally not used. Set to LB_ERR on error (for example, an out of range wParam 
. value). 
Parameters 
hControl HWND: The window handle of the list box control. 
wParam WORD: The index of the item to select. Set wParam to —1 tc deselect all items. 
lParam _ DWORD: Not used. Set equal to OL. 
LB_SETHORIZONTALEXTENT OWin2.0 mWin30 mWin31 
Purpose Sets the width, in pixels, that a list box can be scrolled horizontally. If this value is smaller than 


the list box horizontal size, scrolling is disabled. The list box must have been created with the 
WS_HSCROLL style to apply this message. 


Syntax SendMessage (HWND hControl, LB_SETHORIZONTALEXTENT, WORD wParam, DWORD 
lParam) 

Parameters 

hControl HWND: The window handle of the list box control. 

wParam WORD: The width in pixels that the list box can be scrolled horizontally. 

lParam DWORD: Not used. Set equal to OL. 

LB_SETITEMDATA OWin20 mWin30 mWin3l 
Purpose _ Changes the 32-bit value associated with a list box created with the owner-redrawn style. 
Syntax dwReturned = SendMessage (HWND hControl, LB_SETITEMDATA, WORD wParam, DWORD 

lParam) 

Returns ~ DWORD. Normally not used. LB_ERR on error. 

Parameters , 

hControl HWND: The window handle of the list box control. 

wParam WORD: The index number of the item in the list box. 

lParam DWORD: The new 32-bit value to set. 

LB_SETITEMHEIGHT | OWin2.0 OWin30 mWin3.l 
. Purpose Changes the height of items in an owner-redrawn list box. 

Syntax dwReturned = SendMessage (HWND hControl, LB_LSETITEMHEIGHT, WORD wParam, 

DWORD /Param) 

Returns DWORD. Returns LB_ERR on error. 

Parameters . x 

hControl HWND: The window handle of the list box control. 
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wParam _ WORD: Fora list box with the LBS_OWNERDRAWVARIABLE style, set wParam equal to the 
index of the element which will change height. Otherwise, set wParam equal to zero. All ele- 
ments of the list box will have their height changed. , 


lParam DWORD: Set equal to the new height in pixels. 
Related Messages LB_GETITEMHEIGHT, LB_SETITEMDATA, WM_DRAWITEM 


LB_SETSEL | | eWin20 mWin30 Wind. 


Purpose Selects a string in a multiple-selection list box. The list box must have been created with the 
LBS_MUTIPLESEL style. 

Syntax dwReturned = SendMessage (HWND hControl, LB_SETSEL, WORD wParam, DWORD lParam) 

Returns DWORD, normally not used. Returns LB_ERR on error. 

Parameters 

hControl — HWND: The window handle of the list box control. 

wParam WORD: TRUE to select and highlight the selection. FALSE to deselect and remove highlighting. 

lParam DWORD: The index of the list box item to be set is put in the low-order word. 0 is the index of the 


first item. If /Param is equal to —1, all of the items in the list box are affected. This allows you to 
select or deselect every item in one operation. 


LB_SETTABSTOPS 2 OWin2.0 mWin3.0 mWin31 


Purpose Sets the position of the tab stops to use when displaying items inside of the list box. The unit of 
measurement is the dialog unit, one quarter of the width of a character. The list box must have 
been created using the LBS_USETABSTOPS style to respond to this message. 


' Syntax dwReturned = SendMessage (HWND hControl, LB_SETTABSTOPS, WORD wParam, DWORD 
. lParam) 
Returns DWORD. TRUE if all tab stops were set, FALSE if not. 
Parameters 
hControl HWND: The window handle of the list box control. _ 
wParam 7 - WORD: The number of tab stops to set. If wParam is set to zero and /Param is set to NULL, tab 


stops are set every two dialog units. If wParam is 1, the tab stops are set evenly at a distance 
specified by a single value in /Param. 

lParam DWORD: A pointer to an integer array containing the tab stop position measured in dialog units 
(one-quarter of a character width). The tab stops must be listed in ascending order. Use 
GetDialogBaseUnits() to find out the width of a dialog unit in pixels. 


LB_SETTOPINDEX ae OWin2.0 mWin30 Win3.1 
Purpose Scrolls a list box so that a specified item becomes the top visible item. : 
Syntax dwReturned = SendMessage (HWND hControl, LB_SETTOPINDEX, WORD wParam, DWORD 
lParam) 

Returns DWORD, normally not used. Returns LB_ERR on error. 

Parameters 

hControl HWND: The window handle of the list box control. 

wParam WORD: The index of the item to be shown at the top of the list fied 0 for the first item. 
lParam DWORD: Not used. Setequalto0L... 0. 2... 
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List Box Notification Codes. 

If the user interacts with a list box, Windows sends a WM COMMAND message to the parent window of the list box 
control. The wParam. value passed with WM_COMMAND will be the ID value of the list box control. The window 
handle of the list box is passed as the low-order word in the lParam value. The notification code (see Table 9-13) is in 
the high-order word. 


LBN_DBLCLK Notification that the user double-clicked an item in a list box. 
LBN_KILLFOCUS Notification that a list box has lost the input focus. 

LBN_SELCHANGE Notification that the user has selected or deselected an item in a list box. 
LBN_SETFOCUS Notification that a list box has received the input focus. 


Table 9-18. List Box Notification Code Summary. 


In addition to the LBN messages, Windows will also send a WM_CHARTOITEM message to the owner of the list 
box if the user presses a key while the list box is active. This will happen only if the LBS_WANTKEYBOARDINPUT 
style was used to create the list box. The WM_CHARTOITEM message allows the application to provide a shortcut, 
jumping straight to the first entry in the list box that begins with the given character. WM_CHARTOITEM is docu- 
mented in the last part of this chapter, as the name starts with the WM prefix. | 


List Box Notification Code Descriptions : 
LBN_DBLCLK © : mWin20 mWin30 mWindl 


_ Purpose Notification that the user double-clicked an item in a list box. 
Syntax Returned as part of a WM_COMMAND message, processed by the program’s message processing 
» an 4 _» function (WndProc()). 
Parameters 
wParam WORD: Contains the ID value for the list box control. This is the integer value set for the hier 
. parameter when CreateWindow() was called. 
lParam DWORD: Contains the window handle of the list box in the low-drder word. Contains 7 
. LBN_DBLCLK in the high-order word. . 
LBN_KILLFOCUS OWin20 wWing0 m@Win3 
Purpose Notification that a list box has lost the input focus. 
Syntax Returned as part of a WM_COMMAND message, processed by the program's message aaeescing 
function (WndProc()). 
wParam WORD: Contains the ID value for the list box control. This is the integer value set for the hMenu 
parameter when CreateWindow() was called. 
pice _ DWORD: Contains the window handle of the list box in the low-order word. Contains LBN_| KILL- ; 
os it FOCUS in the igh ontet word. . 
LBN | SELCHANGE 7 ;  @Win20 gWin30 mWin3l 
Purpose Notification that the user has selected or deselected an item in a list box. The list box must have 


been created with the LBS_NOTIFY style for these messages to be received. LBS_NOTIFY is part 
of the hie | STANDARD style. 
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Syntax __ Returned as part; ofa WM _COMMAND® message. processed by the program’s message processing 


. function (WndProc())._ 
Parameters 
wParam WORD: Contains the ID value for the list box control. This is the integer value set for the hMenu 
Poe parameter when CreateWindow() was called. 


lParam : DWORD: Contains the window handle of the list box in the low-order word. Contains 
LBN_SELCHANGE in the high- one word. / 


LBN_SETFOCUS OWin20 mWin3.0 mWin31 

Purpose Notification that a list box has received the input focus. 

Syntax as Returned as part of a WM_ COMMAND message, processed by the program's message processing 
i fiinetion Utndhre0) 

Parameters 

wParam WORD: Contains the ID value for the list box control. This is the integer value set for the hMenu 
. parameter when CreateWindow() was called. 


lParam DWORD: Contains the window handle of the list box i in the low-order word. Contains 
; LBN_SETFOCUS in the high-order word. 


Static Control Messages 


Windows 3.1 has two new messages for working with static controls within a dialog box. STM_GETICON retrieves the 
handle of the icon in an icon control. STM_SETICON changes the icon control to a new icon. 


‘SRM GETICON | | . OWin20 OWin30 mWin3.l 
Retrieves the handle of an icon control. 
a ‘dwketurned = SendDigitemMessage shay hControl, WORD wldon, STM_GETICON, WORD | 
| j wParam, DWORD lParam); 
Returns DWORD. The handle of the icon is in the low-order word of the returned value. Returns NULL on 
(error. 
_ Parameters 

‘ hControl HWND: The window handle of the dialog box. 

wldIcon .>~WORD: The control ID number of the icon control. 

-wParam WORD: Not used. Set equal to 0. | 
lParam DWORD: Not used. Set equal to OL. | - | a 
Related Messages STM_SETICON a oe 

STM_SETICON | sg Win.0  OWin3.0 mw Win3l | 

_ Purpose _ Changes the icon shown in an icon control of a dialog box. 
Syntax... duReturned = SendDigltemMessage (HWND AControl, WORD wldfcon, STM_GETICON, WORD 
* - wParam, DWORD lParam); 
~~ Returns . DWORD. The previous icon’s handle is in the low- baler word of the returned value. Returns zero 
on error. 
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Parameters 


hConirol HWND: The window handle of the dialog box. 

wldIcon WORD: The control ID number of the icon control. 

wParam WORD: The handle of the icon to show in the control. Use LoadIcon() to retrieve this value. 
lParam DWORD: Not used. Set equal to OL. 


Related Messages STM_GETICON 


Window Messages 


All Windows messages are retrieved by GetMessage() or PeekMessage() i in the program’s nies loop, and they are 
ultimately sent to the program’s message processing function, WndProc(). These messages control the operation of 
your program. You can think of a Windows program as an obedient slave. The program just sits there waiting for a 
message. When it receives a message, the program does some task and then goes back to just sitting there. This is 
completely different from a DOS program. DOS programs have an active “mentality.” “First I will do this, then I will do 
that, etc.” 

When GetMessage() sends a message to the program’s WnéProc() function, ane of the elements of the MSG 
structure are turned into parameters. These end up being the hWnd, iMessage, wParam, and [Param parameters 
that WndProc() processes. The other elements of the MSG structure, the message time and mouse cursor location, are 
not sent. They can be retrieved if needed by using GetMessageTime() and GetMessagePos(), described in the previ- 
ous chapter. The iMessage parameter holds the message number. Messages all have coded numbers defined in the 
WINDOWS.H header file. Depending on the message, the wParam and lParam values will have different meanings. 
Listing 9-7 shows an outline of a typical WndProc() function. The function uses the Message parameter to switch to 
the right set of program logic. 


t 


& Listing 9-7. Outline of a WindProc() Function 
tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


# switch (iMessage) /* process windows messages */ 
{ 


case WM_CREATE: 
{* program initialization activities nere x] 
break ; 
case WM_ COMMAND: /* process menu items and child controls */ 
switch (wParam) 
{ 


case ITEM_ONE: ; 
/* program logic for action based’on a menu item or child window control */ 
: break ; 
case WH_ .. Other window messages .... 


- case WM_DESTROY: /*® stop application */ 
DestroyWindow (hWnd) ; ; 
break ; 
default: /* default windows message processing oe 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (COL) ; 


_ There are about 120 different window messages. Fortunately, you normally will use only a handful of these in most 
programs. The most common ones are shown with an asterisk following the message name in Table 9-14. 
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WM_ACTIVATE | Notification that a ey has become active or inactive. 


_ WM _ACTIVATEAPP Notification that the window being activated belongs to another ee program. 
- WN_ASKCBFORMATNAME Windows is requesting that the name ‘of a custom clipboard format be copied into a character 
string buffer. 

WM_CANCELMODE Notification that the system has cancelled a mode it was in. 

_ WM_CHANGECBCHAIN Notification that a window in the clipboard-viewer chain of applications is being removed from 

the chain. | 

WM_CHAR * Transmits the ASCII value of a character key pressed on the keyboard. 
WM_CHARTOITEM Sends the message when the ist box receives a WM_CHAR message. 
WM_CHILDACTIVATE ° Sent to a child window's parent when a child window i is moved. 
WM_CLEAR Deletes the selection in an edit control without copying it to the clipboard. 
WM_CLOSE * . _ Notification that a window will be closed. F 
WM_COMMAND * Notification that the user has selected a menu item or child window control. 
WM_COMPACTING — Notification that the system is tunning low on memory. , 

_ WN_COMPAREITEM Notification that a new item is being added: an owner-redrawn lst box or combo box. 
WM_COPY Copies selected text within an edit contro! to the cata 
WM_CREATE * Notification that a window is being created. 
WM_CTLCOLOR Notification that a child window control is about to be drawn. 
WM_CUT ~. Copies the current selected text from an edit control to the cli pboard. 

_WM_DEADCHAR - Notification that the user has selected a non-English language accent or special character that 
; will change the value of the next character typed. 
WM_DELETEITEM "Notification to the parent of an owner-redrawn combo or list box that an item has been 
removed. 
WM_DESTROY* Notification Hora wien bara des toyed, 
WM_DESTROYCLIPBOARD Notification to the clipboard owner that the clipboard has been emptied by a calito 
EmptyCiipboardt ). 


WM_DEVMODECHANGE __- Sent to all top-level windows when the user changes the name of a device in the WIN.INI file. 
WM_DRAWCLIPBOARD Sent automatically by Windows to the frst window of the clipboard viewer chain wie the 


contents of the clipboard change. 
WN_DRAWITEM | Notification to the owner of a owner-drawn button, list box, or combo box, that one of the items 

in the list has changed. 
WW_DROPFILES Sent when the left mouse button is released over an application which is registered as a 

recipient of dropped files. (Win 3.1) 
WM_ENABLE . ~——_-_Nottification that a window has been enabled or disabled. = - 
WM_ENDSESSION __ Final notification that the Windows session is being stopped. : 
WM_ENTERIDLE = Noticaton that modal dog box or menu as been activated, buthas no messge 

4 process. 
WM_ERASEBKGND Alfieri baseline of & iviciow's char era Fnac io HS rapt 
WM_FONTCHANGE ; . Notification that the number of fonts available to applications has changed. 3 
WM | GETDLGCODE Notification that the user is using the direction arrow keys or the (Zi) key from within a dialog . 
© (BOX. - : eg 7 


WM_GETFONT 
WM_GETMINMAXINFO 


WM_GETTEXT 
_ WM_GETTEXTLENGTH 
WM_HSCROLL * 


WM_HSCROLLCLIPBOARD — 


WM_ICONERASEBKGND 
WMINITDIALOG 
WM_INITMENU 
WM_INITMENUPOPUP 
WM_KEYDOWN * 
WM_KEYUP 
WM_KILLFOCUS. 

_ WM_LBUTTONDBLCLK 
WM_LBUTTONDOWN * 
WM_LBUTTONUP 
WM_MBUTTONDBLCLK 
WM_MBUTTONDOWN. - 
-WM_MBUTTONUP 
WM_MDIACTIVATE 


WM_MDICASCADE 
WN_MDICREATE 
WM_MDIDESTROY 
WM_MDIGETACTIVE . 
| WM_MDICONARRANGE 


WM | MDIMAXIMZE 
WM_MDINEXT 
WM. MDIRESTORE 
WM_MDISETMENU 
WM_MDITILE 
.WM_MEASUREITEM 
WM_MENUCHAR 


~ WM_MENUSELECT 
WM_MOUSEACTIVATE 
, WM_MOUSEMOVE 
-- WN_MOVE *. 
~ WM_NCACTIVATE 
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Retrieves the font currently being used by a child window control. - 


Notifies the application that Windows is checking me size for the window when minimized or 
maximized, 


Used to copy text from a child window control into a character buffer. 
Used to determine the number of characters in a child window control. -. 
Notification that the user has adjusted a horizontal scroll bar. 
Indicates that the clipboard viewer horizontal scroll bar has been used. 
Notification that a minimized (iconic) window needs to have the background painted. 
Notification that a dialog box is about to be displayed. - 

Notification that the user has clicked a main menu item. 

Notification that the window is about to display a popup menu. 
Notification that a key was pressed. 

Notification that a key was released. 

Notification that a window is about to loose the input focus. 

Notification that the user has double-clicked the left mouse button. 


Notification that the user has pressed the left mouse button. 


Notification that the user has released the left mouse button. 
Notification that the user has double-clicked the center mouse button. 
Notification that the user has pressed the center mouse button. 
Notification that the user has released the center mouse button. 


Used to activate and deactivate child windows within a Multiple Document Interface won 
window. 


Arranges ail of the child windows within the MDI client window i in beac format. 


Creates an MDI child window. 
Destroys (removes) an MDI child window. 
Obtains the handie of the currently active MDI child window. 


Causes the MD! client window to Pere all minimized MDI child windows at the bottom of the 
Client area. 


Causes an MDI child window to be maximized. 

Activates the next MDI child window. 

Restores a MDI child window to its previous size. 

Links a menu to the MDI frame window. 
Causes an MDI client window to arrange all of its children in tile format. 
Allows owner-drawn buttons, list boxes, and combo boxes to be sized. 


Informs the application that the user attempted tousea re shortcut for a menu selection 
that did not match any menu item. 


Notification that the user has selected a menu item. 

Notification that the cursor is in an inactive window and the user clicked a mouse button. _ 
Notification that the user has moved the mouse. 

Notification that a window has been moved. 


Rosin ted eve rea of ei eee oS erga te a co 
inactive state. 
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Table 9-14. continued — 


WM_NCCALCSIZE 


WM_NCCREATE 
WM_NCDESTROY 


WM_NCHITTEST 
WM_NCLBUTTONDBLCLK 


- WM_NCLBUTTONDOWN 
- WM NCLBUTTONUP 
in Cue OMpaLGHe 
WM_NCMBUTTONDOWN 
WM_NCMBUTTONUP 


WM_NCMOUSEMOVE 
WM_NCPAINT 
WM.:NCRBUTTONDBLCLK 


WM_NCRBUTTONDOWN 
WM_NCRBUTTONUP 


WM_NEXTDLGCTL * 


WM_OTHERWINDOW- 
CREATED 


WM_OTHERWINDOW- 
DESTROYED 


WM_NULL 
WM_PAINT * 
WM_PAINTCLIPBOARD 
WM_PAINTICON 
WM_PALETTECHANGED 
WM_PARENTNOTIFY 


WM_PASTE 
WM_QUERYDRAGICON 


Sent when the size of a pat acd t ths itl, border, and ee areas, nosis to be 


recalculated. 
Notification that Windows is about to create the nonclient area of the window. 


Informs a window that its nonclient area is being eed This message is sent after . 
WM_DESTROY. 


Sent to the window that has the mouse, or that used GetCapture() to capture all mouse input. 


Notification that the user double-clicked the left mouse button while the mouse cursor was in 
the nonclient area of the window. _ 


Notification that the user pressed the left mouse button while the mouse cursor was in the 
nonclient area of the window. 


Notification that the user released the left mouse button while the mouse cursor was in the 
nonclient area of the window. a4 


Notification that the user double-clicked the center mouse button while the mouse cursor was 
in the nonclient area of the window. 


Notification that the user has pressed the center mouse button while the mouse cursor was in 
the nonclient area of the window. 


Notification that the user released the center mouse button while the mouse CuSON was in the 
nonclient area of the window. = ae 
Notification that the mouse has been moved in the nonclient area of the ver 

Notification that the noncliént area of a window needs to be repainted. 


Notification that the uSer double-clicked the right mouse button while the mouse cursor was in 
the nonclient area of the window. 


Notification that the user pressed the right mouse button while the mouse cursor was in the 
nonclient area of the window. 


Notification that the user released the right mouse button while the mouse cursor was in the ’ 
nonclient area of the window. 


Moves the input focus to another child window control within a dialog box. 


Sent to all overlapped and popup windows running in the system when a new top-level window 
is created. (Win 3.1) 


Sent to all overlapped and popup windows running in the system when a new peo" window 
is destroyed. (Win 3.1) 


No action is taken. 

Notification thatthe client area of a window needs to be repainted. 

Used by clipboard viewer applications as notification that the viewer data should be repainted. 
Notification that a minimized (iconic) window needs to be repainted. 


"Notification that the system color palette has changed. - 


Notification to the parent window that a acme window is being created, ie or is being 
clicked with the mouse. 


Copies the text from the clipboard io an edit control. 
Notification that the user is about to move a minimized window. 
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WM_QUERYENDSESSION 


~- WM_QUERYNEWPALETTE 


WM_QUERYOPEN 
WM_QUIT 
WM_RBUTTONDBLCLK 
WM_RBUTTONDOWN 
WM_RBUTTONUP 
WM_RENDERALLFORMATS 


WM_RENDERFORMAT 


WM_SETCURSOR 
WM_SETFOCUS * 
WM_SETFONT 
WM_SETREDRAW 
WM_SETTEXT * 
WM_SHOWWINDOW 
WM_SIZE* | 
WM_SIZECLIPBOARD 
WM_SPOOLERSTATUS 


WM_SYSCHAR 


_ WM_SYSCOLORCHANGE 


‘ 


WM_SYSCOMMAND 
WM_SYSDEADCHAR . 
WM_SYSKEYDOWN 
WM_SYSKEYUP 
WM_TIMECHANGE 
WM_TIMER: * 
WM_UNDO — 
WM_USER 


~ WM_VKEYTOITEM 


WM_VSCROLL * 
WM_VSCROLLCLIPBOARD 
WM_WININICHANGE 
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Notification that the Windows session is about to be ended. 
Notification that an application is about to receive the input focus. 
Notification that a minimized window is about to be restored. a 
This is the final message processed by an application. 
Notification that the user double-clicked the right mouse button. 
Notification that the user pressed the right mouse button. 
Notification that the user released the right mouse button. 


Notification to the owner of one or more clipboard formats that the application program is . 
exiting. 


Notification to the owner of the clipboard that data should be bas into the clipboard in the 
specified format. 


Notification that the mouse Cursor is moving within a window. 

Notification that a window has gained the input focus. 

Used to change the font used in dialog box controls. 

Sent to list box and combo box controls prior to adding or deleting a a number of items. 
Used to change the title or text of a window. 

Notification that a window is to be hidden or shown. 

Notification that the size of a window has changed. 

Notification that the clipboard viewer application has changed size. 


Notification from the Print Manager that a job has been added or subtracted from the aad 
Queue. 


Generated by TranslateMessage() i in the application’s message loop when a WM_; SYSKEYUP _ 
or WM_SYSKEYDOWN message is processed. . 


Notification that one or more of the system colors has changed. 
Notification that the user selected a system menu command. 
Notification of a system dead character. : 
Notification that the user pressed a key while holding down the key. 

Notification that the user released a key while holding down the key. 

Notification that the system clock has been changed. te 
Notification that one of the timers set with the SetTimer() function has passed its time interval. 
Copies the text from the clipboard to the edit contro'’s client area. 
Programmer-defi ned messages are from WM_USER to Ox7FFF. 

Notification that the user pressed a key while a list box had the input { focus. 

Notification that the user adjusted a vertical scroll bar. ; 

Indicates that the Clipboard viewer vertical scroll bar has been used. 

Notification: that the WIN.INI file has been changed. 


* Most frequently used messages. _ 


. Table 9-14. Window Message Summary, . 
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Window Message Descriptions 


WM_ACTIVATE | mWin2.0. mWin3.0 wWin3dl 


Purpose Notification that a windoa has become active or inactive. The active window receives all key- 
- board input and will have a highlighted caption area or dialog frame (for dialog boxes). 
Parameters . 
wParam WORD: 0 if the window is inactive. 1 if the window became active via keyboard input or a Set- 
ActiveWindow() function call. 2 if the window became active via mouse input. Usually, it is not 
important how a window becomes active, so the program c can just check for wParam to be non- 
zero for active status. 
lParam DWORD: The high-order word is nonzero if the window is minimized, zero if not. The low-order 
, = word is a handle to the window becoming active if wParam is 0, or a handle to the window 
becoming inactive if wParam is nonzero. In the latter case, the low-order word may be NULL, if — 
no prior window was active. 
WM_ACTIVATEAPP @Win20 mWin30 mWin31 
Purpose - Notification that the window being activated belongs to another application program. This mes- 
sage is sent to both the window becoming active and the window becoming inactive. 
Parameters ; . a 
wParam WORD: Nonzero if the window is becoming active, zero if the window will become inactive. 
- Param DWORD: The task handle for the application program. If wParam is zero, the low-order word of 
a lParam contains the task handle of the application that owns the window being deactivated. If 
wParam is nonzero, the low-order word of [Param contains the task handle of the application 
‘that owns the window being activated. The task handles for all running programs can be found 
using the EnumTasks() function. a 
WM_ASKCBFORMATNAME mWin20. wWin30 mWin3! 
Purpose Requests that the name of a custom clipboard format be copied into a character string buffer. 
. This message is used with the CF OWNERDISPLAY format of clipboard data. 
Parameters . 
wParam WORD: Specifies the maximum number of bytes to copy. 
lParam. DWORD: A far pointer to the buffer which will hold the clipboard data format name. Your pro- 
gram should save the clipboard format name in this buffer when the WM ASKCBFORMATNAME 
message is received. 
WM_CANCELMODE | @Win20 m@Win30 mWin3l 
Purpose Notification that the system has cancelled a mode it was in. For example, this message is sent 
whena message box or system modal dialog box is displayed, or when a scroll bar is Geen, or when 
a window is moved. 
- Parameters - 
wParam WORD: . Not iad 
lParam _ DWORD: Not used. 
WM_CHANGECBCHAIN 3 mWin20 mWin30 wm Wind, 
Purpose. Notification that a window in the clipboard viewer chain of applications Is being: removed from - 


the chain. Each window receiving this message should use SendMessage() to La the nene | 
on to the next window i in the chain. See Chapter 17 fordetails. 
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WORD: The handle of the window being removed from the clipboard viewer chain. 


DWORD: Contains the handle of the next window in the clipboard viewer chain. If the window 
being removed is the next window in the chain, clipboard messages will be passed to the window 
who’s handle is specified in /Param. 


@Win2.0 Bwn30 GWind! 


Transmits the ASCII value of a character key pressed on the keyboard. This message is generated 
by the TranslateMessage() function in the program’s message loop. 


WORD: The ASCII value of the key pressed. 


DWORD: Contains coded data about the key pressed, as shown in Table 9-15, as this data is 
ignored. 


0- 15 ran order wiad The iepasil ou This! is its naib of ines ane ae was oun SaaS the user 


held down a key. 
16-23 The keyboard scan code. 
94 1 if an extended key, such as a function key or a key on the numeric keypad. 
25-28 Not available. : 
29 1 if the Gaur) key was held down when the key was eahbil 0 if not. 
30 1 if the key is down beforé the message was sent, 0 if not. 
31 


1 if the key is being released, 0 if the key is being pressed, 


Table 9-15. WM_CHAR |Param Coding. . 
WM_CHARTOITEM 0 Win 2.0 Win3.0  @Win3.1 


Purpose 


This message is sent by a child window list box control to its parent. The list box must have been 
created with the LBS_WANTKEYBOARDINPUT style to generate this message. The message is 
sent when the list box receives a WM_CHAR message. The message allows a keyboard shortcut to 
be added for quick selection of the first list box item that starts with the given character. The 
window processing function should return a value in response to receiving this message. A re- 
turned value of zero or greater specifies the index of a selected item in the list box. A returned 
value of —1 specifies that the list box should do its default processing of keyboard input (usually 

ignored). A returned value of -2 specifies that no action should be taken by the list box. , 


Parameters 
wParam WORD: The ASCII value of the key the user pressed. 
lParam DWORD: Contains the current caret position in the high- order word and the window handle of 
the list box in the low-order word. 
WM_CHILDACTIVATE Ste wWin20 wWind0 mWin3.! 
Purpose Sent to a child window's parent when a child window is moved or activated. For ee after 
_ . SetWindowPos() is used to move a child window. . 
Parameters : : ; 
wParam — ’ WORD: Notused. ~ 
lParam 


DWORD: Not used.’ 
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WM_CLEAR GWin2.0 eWind0 mWin3l 


Purpose Notification that the user is 3 deleting & the current selection in an edit control without copying vying it to to 
the clipboard. 

Syntax SendMessage (HWND hControl, WM_CLEAR, WORD wParam, DWORD lParam) 

Parameters 

hControl HWND: The edit control’s window handle. 

wParam WORD: Not used. Set to 0. 

lParam DWORD: Not used. Set to OL. 

WM_CLOSE | mw Win2.0 mWin30 wWin3.1 

Purpose Notification that a window will be closed in response to the user pressing (atr)-(Fa) or selecting 


“close” from the-system menu. Passing this message to DefWindowProc() calls the Destroy- 
Window() function. Intercepting the message prevents the SHOW. from being cee 


(closed). ; 
Parameters ” : 
wParam WORD: Not used. 
lParam DWORD: Not used. 
WM_COMMAND ___ i | wWin2.0 wm Win8.0 Wind) 
Purpose Notification that the user has selected a menu 1 item or child window control, or has used an 
accelerator key. : 
Paramcters 
wParam WORD: Contains the menu item or child window control ID value. For child window controls, the 
ID value is specified as the hMenu parameter when CreateWindow() is called. 
‘Param DWORD: The low-order word is zero if the message is from a menu item selection. The high-order 
word is one if the message is from an accelerator keystroke. If the message is from a child window 
control, the high-order word is the notification code (such as BN_CLICKED), and the low-order 
word is the window handle of the control. 
WM_COMPACTING gw ___. Oo Win2.0 Windom Win3.1 
Purpose Notification that the system is running low on memory. Windows determines when to send this 
message by calculating how much time is spent compacting memory. When more than 12.5% of 
the processing time is going into memory compacting, WM_COMPACTING is sent to all active 
applications. ee receiving this message should free as much memory as possible. 
Parameters . 
wParam WORD: Specifies how citi CPU time is going into combactite memory. OXFFFF i is 100%, vad 
a % is 0%, a® - 
lParam DWORD: Not used. | | ) 
WM_COMPAREITEM Win 2.0 Win3.0 Wind 
Purpose Notification that a new item is being added into an owner-redrawn list box or combo box created 


with the LBS_SORT or CBS_SORT styles: Windows uses the COMPAREITEMSTRUCT data struc- 
ture to facilitate comparison of items. This structure is defined in WINDOWS.H as follows: 


~ 


/* COMPARELTEMSTRUCT for ownerdraw sorting */ 
typedef struct tagCONPAREITEMSTRUCT 
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{ | a : 
WORD CtlType; e /* ODT_LISTBOX, or ODT _COMBOBOX*/ “3 
WORD Ctlio; /* control id number for the List box, or combo box */ 
HWND hunditem; | /* control window handle */ 
WORD itemID1; /* item id 1 */ 
DWORD : itemData1; /* item 1s 32-bit vatue */ 
WORD item1D2; /* item id 2 */ 
DWORD itemData2; /* item 2s 32-bit value */ 


} COMPAREITEMSTRUCT; 
typedef COMPAREITEMSTRUCT NEAR *PCOMPAREITEMSTRUCT; 
typedef COMPAREITEMSTRUCT FAR *LPCOMPAREITEMSTRUCT; 


When the program owning the list or combo box receives this message, it should return a 
value specifying the relative ordering of the two items referenced in the COMPAREITEMSTRUCT 
as follows: 


—l Item 1 comes before item 2. 
0 Item 1 and 2 sort the same. 
‘1 Item 2 comes before item i 


Typically, the program owning the list or combo box will receive this message a number of 
- times, until the position of the new item can be completely determined. See the example owner- 
redrawn combo box in the combo box section of this chapter. 


Parameters 

wParam WORD: Not used. . 

lParam DWORD: Contains a far pointer to a COMPAREITEMSTRUCT. 

‘WM_COPY he os S : - we Win20 BWind0  aWind! 

Purpose Copies selected text within an edit cantel to the clipboard. The text is stored in CF_’ TEX’ [ format 
in the clipboard. 

Syntax SendMessage (HWND hControl, WM_COPY, WORD wParam, DWORD Param) 

Parameters 

hControl HWND: The edit sonteohe window tance 

wParam WORD: Not used. Set to 0. 

lParam DWORD: Not used. Set to OL. 

WM_CREATE be? BWin20 BWind0 mWin3l 

Purpose Notification that a window is being created. This is a good place to do program data initialization | 
and startup routines. This message is processed before CreateWindow() returns and before the 
window i is made visible. 

Parameters 


wParam. « ¢~,.- WORD: Not used 
lParam: ; ee WORD» A far pointer to a CREATESTRUCY data struc ture. ane structure is dened i 


hat Dae 


"-4 WINDOWS.H as follows: . FOES 
typedef struct tagCREATESTRUCT ee na eas 
. c ; . 


.. LPSTR 7 tpCreateParams; 


" HANDLE - hiInstance; 
HANDLE og hMenu; 
HWND - hwndParent; 
int cy; : 
int Cx; 
int y¥; 
int xX; 
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LONG style; 


LPSTR lLpszName; | 
LPSTR Lps2Class; 
DWORD ; dwExStyle; 


} CREATESTRUCT; 
typedef CREATESTRUCT FAR _ *SLPCREATESTRUCT; 


WM_CTLCOLOR mWin2.0 . @Win3.0 mWin3.1 
Purpose Notification that a child window control is about to be drawn. This gives the parent program a 
chance to change the default colors for the text and background used. The WndProc() function 
receiving this message can load a brush to paint the background and return the handle to the 
brush. If the brush uses a pattern, call UnrealizeObject() to align the brush with the upper left 
corner of the object before returning the handle to the brush. 


Parameters 


wParam WORD: The display context for the child window control. Equivalent to the returned value from 
GetDCQ). : 
lParam DWORD: The low-order word contains a handle to the child window control. The high-order word 


contains one of the values listed in Table 9-16. | 


CTLCOLOR, BIN Button control. 
CTLCOLOR_DLG A dialog box. 
CTLCOLOR_EDIT An edit control. 
CTLCOLOR_LISTBOX A list box control. 

" CTLCOLOR_MSGBOX A message box. 
CTLCOLOR_SCROLLBAR —Ascroll bar control. 
CTLCOLOR_STATIC A static text control. 


Table 9-16. WM_CTLCOLOR Values. . ae 


Warning If the application program processes the WM_CTLCOLOR message, it must return a 1 handle to 
the brush to use in painting the background of the window. Otherwise, the system will crash. 


WM_CUT 7 mWin20 mWin30 w@Windl 


Purpose Copies the current selected text from an edit control to the clipboard, and then deletes the ect 
from the edit control's client area. 


Syntax SendMessage (HWND hControl, WM_CUT, WORD wParam, DWORD i 


Parameters 
hControl . HWND: The window handle of the edit control. 


wParam WORD: Not used.. 
lParam - DWORD: Not used. 


WM_ DDE _ACK to WM_DDE_UNADVISE 
These messages are covered in Chapter 30, Dynamic Data Exchange, and are defined in the 
DDE.H header file. 


WM_DEADCHAR . wWing0 wWing0. wWindl 


Purpose Notification that the user selected a non-English language accent or special character that will 
"a = change the value of the next character typed. This occurs when WM_KEYUP and WM_KEYDOWN 
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messages for special characters are sent. The character following the dead character is the ac- 
_ Cent or special character. For example, if the system is using German as the default language 
(determined by the Setup program during installation of Windows), the sequence dead key, um-, 
laut, and the O key will be sent to create an umlauted 0. . 


Parameters 

wParam WORD: The repeat count (the number of times the key was repeated as a result of the kéy being 
held down). 

lFaram DWORD: Contains coded data about the key presed Usually this data is ignored. (See Table 9-17 


for information.) 


0-15 (low order word) The repeat count. This is the number of times the character was repeated because the user 


held down a key. 

- 16-23 The keyboard scan code. 

24 1 if an extended key, such as a function key or a key on the numeric keypad. 

25-28 Not available. e 

29 1 if the GED key was held down when the key was pressed, 0 if not. 

30 1 if the key was down before the message was sent, 0 if not. 

31 1 if the key is being released, 0 if the key is being pressed. 
Table 9-17, WM._DEADCHAR lParam Coding. | . 
WM_DELETEITEM | OWin2.0 mWin3.0 ms Win3.1 
Purpose . _ _ Notification to the parent of an owner-redrawn combo or list box that an item has been removed. 


~ This is sent when a single item is removed or the entire box has had its contents reset, or when 
the list or combo box is destroyed. The message includes a pointer to a DELETEITEMSTRUCT 
structure, defined in WINDOWS.H as 


/* DELETEITEMSTRUCT for ownerdraw */ 
ene struct tegDELETEITERSTRUCT 


WORD CtlType; /* ODT_LISTBOX, or ODT_COMBOBOX */ 


woRD Celio; /* control id number for the List box, or combo box */ 
. WORD itemID; - /* the itea's id number in the List or combo box */ 

WUND hunditemn; /* control window handle */ 

DWORD itemData; /* item's 32-bit data */ 


> DELETEITEMSTRUCT; 
typedef DELETEITEMSTRUCT NEAR *PDELETEITEMSTRUCT; 
typedef DELETEITEMSTRUCT FAR *LPDELETELTEMSTRUCT; 


You can use this message to free any memory associated with bitmapped i images or similar 
objects if they are no longer needed by the list or combo box. The message may be received more 
. than once if several items are oe deleted. 


wParam | ‘ WORD: Not used. 
iad DWORD: A far pointer to a DELETEITEMSTRUCT structure for the item ms deleted 


WM_DESTROY | eWin20 wWin30 mWin3l 


Purpose Notification that a window is being destroyed after it has been removed from the screen. This 
Message is sent to the window after the window image. is removed from the screen. 
WM_DESTROY is sent to the parent window before any of the children are destroyed. If the 
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window being destroyed is part of the clipboard viewer chain, the window must remove itself. 
from the chain by calling ChangeClipboardChain(). If the window being destroyed is the last ap- 
plication window, without a parent, it should call PostQuitMessage() in response to this message. 


Parameters 

wParam WORD: Not used. 

lParam DWORD: Not used. 

WM_DESTROYCLIPBOARD. sas Win2.0_s Win 3.0‘ mWin311 

Purpose Notification to the clipboard owner that the eae has been emptied by a call to 
EmptyClipboard(). 

Parameters 

wParam WORD: Not used. 

lParam DWORD: Not used. 

~ WM_DEVMODECHANGE | @Win2.0 m@Win380 mWin3) 

Purpose Sent to all top-level windows when the user changes theiname of a device in the WIN.INI file. 

Parameters | 

wParam - WORD: Not used. 

lParam DWORD: A pointer to a character string containing the name of the device changed in WIN.INI. 

- WM_DRAWCLIPBOARD mg Win2.0 sm Win3.0 mw Win3.l 

Purpose Windows automatically sends. this message to the first window of the clipboard viewer chain 
when the contents of the clipboard change. Each window in the chain should send the message . 
on.to the next window in the viewer chain. A handle to the next window i in the chain canbe 

. obtained with Seren peaan Viewer: . 

Parameters 

wParam WORD: Not used. 

lParam _ DWORD: Not used. . . 

WM_DRAWITEM | | | OWin20 mWin30 mWin3.l 

Purpose — Notification to the owner of an owner-drawn button, list box, or combo box that one of the items 
in the list has changed. The message passes a pointer to a DRAWITEMSTRUCT Eeueue defined 

- in Windows as 


/* DRAWITEMSTRUCT for ownerdraw */ 
typedef struct tagDRAWITEMSTRUCTL 


WORD CtlType; /* ODT_MENU, ODT_LISTBOX, ODT_COMBOBOX, or ODT_BUTTON */ 
WORD . CtlId; /* control id number for the List box, combo box or button */ 
WORD itemID; /* the item's id number in the list-or combo box */ - 

WORD jtemAction; . /* ODA_DRAWENTIRE, ODA_SELECT, or ODA_FOCUS */ 

WORD itemState; ©“ /* ODS_SELECTED, ODS_GRAYED, ODS_DISABLED, ODS_CHECKED */ 
HWND . hwndIitem; /* the item's handle */° /* or ODS_FOCUS */ 
HDC hoc; : /* the item's device context */ , s 

RECT reItem; /* the bounding rectangle of the item */ 

DWORD itemData; — /* here is where the 32-bit data goes */ 


} DRAWITEMSTRUCT; 
typedef DRAWITEMSTRUCT NEAR *PDRAWITEMSTRUCT; 
typedef DRAWITEMSTRUCT FAR *LPDRAWITEMSTRUCT; 


The ttemAction element of the structure determines if the element is to be drawn, shown as 
“selected, or shown as having the focus, Be sure to release any objects used to draw the item 
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before returning from processing this message: An example of an owner-drawn combo box ap- 
pears in the combo box section of this chapter. 


Parameters 

wParam WORD: Not used. 

lParam DWORD: A far pointer to the DRAWITEMSTRUCT structure for the item. 

WM_DROPFILES OWin20 OWin30- gWin31 

Purpose Sent when the left mouse button is released over an application which is registered as a recipient 
of dropped files. 

Parameters . 

wParam - WORD: Contains a handle to an internal data structure describing the dropped files. The new 
Windows 3.1 registration functions are used to create these data structures. 

lParam DWORD: Not used. 

WM_ENABLE BWin20 mWin30 wWin3.1 

Purpose Notification that a window has been enabled or disabled. Disabling is used to stop a child window 

- button control from functioning. The text inside of the button is grayed. The EnableWindow() 

function is used to change a window's status to/from enabled or disabled. 

Parameters 

wParam _ WORD: Nonzero if enabled, zero if disabled. 

lParam DWORD: Not used. — 

WM. _ENDSESSION eWin20 8Win30 oWin3.1 

Purpose Final notification that the Windows session is being stopped. This message follows WM_QUERY- 

_ ENDSESSION, if all windows returned a nonzero response to that message. 
Parameters 
wParam WORD: Nonzero if the Windows session is being ended, zero if not. If a nonzero value is sent, 

Windows can terminate at any time. The application should save any data in preparation for 
termination. ~ 

lParam DWORD: Not used. 

WM_ENTERIDLE Win2.0 m@Win3.0 mWin3.1. 

Purpose Notification that a modal dialog box or menu has been activated, but has no messages to process. 
This is a good point to set a timer if the dialog or message block should be removed autonaucally: 

Parameters 

wParam _ _ WORD: Contains MSGF_DIALOGBOX or MSGF_MENU if the system is idle due toa oa dag box or 

‘ menu, respectively. 

lParam DWORD: The low-order word contains the handle of the dialog box or the window containing the 

menu. The high-order word is not used. 
WM_ERASEBKGND | mWin2.0 wWin3s.0 wWin31 
Purpose Notification that the background of a window’s client area needs to be repainted. Normally, the 


background is repainted using the brush specified in the window’s class definition. If no back- 
ground brush was specified in the class definition (kbrbackground = NULL), the application 
- should process WM_ERASEBKGND messages. If the background brush contains a pattern, use 


oo 
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UnrealizeObject() to align the brush with’ the window's top left corner. Be sure the window's 
device context is in the default MM_TEXT mapping mode before using this fanction to avoid 
painting only a portion of the client area. 


Parameters 

wParam . WORD: Contains the device context handle for the background. 

lParam . DWORD: Not used. 

Returns The function processing this message should return nonzero if the background was erased, zero if 
not. 

WM_FONTCHANGE | BWin20 weWin30 mWin3.1 * 

Purpose Notification that the number of fonts available to applications has changed, probably because an 
application used the AddFontResource() or RemoveFontResource() function. Any application 

. that changes the fonts on the system should send this message to all running applications. (Using 

‘ PostMessage() with hWnd set equal to OxFFFF, sends a message to all applications.) 

Parameters \ 

wParam WORD: Not used. ans 

lParam DWORD: Not used. 

WM_GETDLGCODE - BWin20 mWin30 mWin3.l 

Purpose Windows sends this message to a control's input procedure. This allows the control to specify to 
what type of keyboard input the control will respond. Generally used in creating custom controls. 

Parameters 

wParam ‘WORD: Not used. 

lParam DWORD: Not used. 

Returns The application receiving this message should return one or more of the following values, com- 


bined using the C language binary OR operator (1). This will establish which types of messages 
are, as listed in Table 9-18, processed by the program, esanine Windows’ default sa a han- 


_ dling. 
DLGC_ARROWS The direction keys. 
DLGC_DEFPUSHBUTTON Default pushbutton. 
DLGC_HASSETSEL EM_SETSEL messages. 
DLGC_PUSHBUTTON " All pushbuttons. 
DLGC_RADIOBUTTON All radio buttons. 
DLGC_WANTALLKEYS All keyboard input. 
DLGC_WANTCHARS =~ WM_CHAR messages. ; 


DLGC_WANTMESSAGE All keyboard input (the appl ei passes this message to me contro). 
DLGC_WANTTAB , The tab key. _ 


Table 9-18. WM _GETDLGCODE Return Flags. 


WM _GETFONT a a 7 OWn2.0 @Win30 sWin3l © 
Purpose - Retrieves i font currently being used by a child window control I(edit, static text, list eens etc. ye 
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Syntax dwFont = SendMessage (HWND hControl, WM_GETFONT, WORD wParam. DWORD ia 


Returns aia the handle to the font. NULL is the system font. 

Parameters 

hControl Hin: The window handle of the child window control. ae 

wParam ~ WORD: Not used. 

lParam DWORD: Not used. : 
WM _GETMINMAXINFO Win20 wWin3.0 eWin3) 
Purpose Notifies the application that Windows is checking the size of the window when minimized or 


maximized, giving the application a chance to change the default values. This message is sent by 
CreateWindow() before CreateWindow() returns. Use the GetSystemMetrics() function to re- 
trieve the size of the screen, window borders, menu bar, etc. as needed to calculate the size of 
window your application needs. 


Parameters 
wParam WORD: Not used. 
- Param DWORD: A far pointer to an array of five POINT structures. Each point holds the X and ¥Y di- 
mensions in pixels for the window in one of several states. The point array values are listed in 
Table 9-19. 


rapt{0} . Used Sienehy ay Windows, 


rgpt[1} The maximized size. Defaults to the screen size. 
rgpt[2) The position of the upper left corer when the window is maximized. The default values are SM_CXFRAME, 
SM_CYFRAME for X,Y. * 
rgpt[3) The smallest tracking size. The minimum tracking size is the smallest size obtainable i using the borders 
to adjust the window size. The default minimum is equal to the icon size. 
rapt The maximum tracking size. Defaults to the screen size. The maximum tracking size is the largest size 


obtainable by using the borders to adjust the window size. 
Table ip 19. WM _GETMINMAXINFO Point Array Values. 


The array of five points is initialized to the default values when the message is transmitted by 
Windows. The application can change any of the values in the array before returning control to 
~. Windows. The modified values are then used by Windows to size the application’s window. 


WM_GETTEXT | sg Win.0 )«sWin3.0 sm Win3.l 

Purpose Used to copy text from a child window control into a character buffer. For edit and combo box 
controls, the text to be copied is the contents of the edit box. For buttons, it is the button text. For _ 
list boxes, the text is the currently selected item. For other windows (child windows, popups), the - 
text is the window’s epee: Sending this message is ee to calling the Gerwindowrextt) 


* function. » 
Syntax dwReturned = SendMessage (HWND hConirol, BM. -GETTEXT, WORD en DWORD 
lParam) 
Returns '  DWORD, the number of characters copied. It is LB ERR or CB_ERR if the control i is a list or 
, as box, but no selection has been made. 
Parameters 
hControl HWND: The window handle of the child window control. 


ares 


= ws ee 


wParam WORD: The maximum number of characters to copy. 


lParam _ DWORD: A far pointer to a character buffer that will receive the string. 
WM_GETTEXTLENGTH gw Win2.0 sm Win8.0 Win 3.1 
Purpose Used to determine the number of characters in a child window control. For edit and combo box 


controls, the text is the contents of the edit box. For buttons, it is the button text. For list boxes, 
the text is the currently selected item. For other windows (child windows, popups), the text is the: 
window's caption. Sending this message is equivalent to calling the GetWindowTextLengthQ) 


function. 
Syntax dwReturned = SendMessage (HWND hControl, BM _GETTEXTLENGTH, WORD wParam, 
DWORD /Param) 
Returns _ DWORD, the number of characters in the control. \ 
Parameters _ 
hControl HWND: The window handle of the child window control. 
wParam _ WORD: Not used. 
lParam DWORD: Not used. 
WM_HSCROLL 7 | Win2.0 mWin30 em Win3l 
Purpose Notification that the user has adjusted a horizontal scroll bar. 
Parameters 
wParam WORD: One of the codes in Table 9-20. 


SB_! BOTTOM Geraiad if the scroll bar hs the input focus ard the 5 Gm) aii is spresed Not generated by 


mouse actions. 
SB_LENDSCROLL Sent when the scroll activity stops. 
SB_LINEDOWN Clicked the arrow on the left. 
SB_UNEUP Clicked the arrow on the right. 
- SB_PAGEDOWN Clicked the area of the scroll bar between the left arrow and the thumb. 
SB.PAGEUP . _ Clicked the area of the scroll bar between the right arrow and the thumb. 
SB_THUMBPOSITION The message passes the position of the thumb as the low-order word of Param. 2 
SB_THUMBTRACK —>—sSThe thumbis being dragged. The current position is passed as the low-order word of [Param. 
SB_TOP . Generated if the scroll bar has the input focus and the (HOME) key is pier Not generated by 
mouse actions. 


Table 9-20. Scroll Bar Codes. 


‘(lParam » DWORD: The high-order word contains the window handle of the scroll bar. If the scroll bar is 

attached to a the boundary of a popup window, the high-order value is not used, The low-order 
_ word contains the thumb posruron it if either the SB _THUMBPOSITION « or ‘SB_ THUMBTRACK value 
for wParam is passed. 


WM: HHSCROLLCLIPBOARD 7 aWin2.0 mWin30 Wind 


2 Purpose Used with the CF_OWNERDISPLAY format of data type for the clipboard used by clipboard viewer 
programs. The message indicates that the clipboard viewer horizontal scroll bar has been used. 
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- Parameters 
wParam ‘WORD: Contains a handle to the clipboard viewer program. 
lParam DWORD: The low-order word contains one of the scroll bar codes nea in Table 9-20, used in 
WM_SCROLL messages. The high-order word contains the thumb position if the SB_THUMB-. 
POSITION or SB_THUMBTRACK value is passed in the low-order word. sO BETS, the high- 
order word is not used. 
- WM_ICONERASEBKGND | OWin2.0 mWin3.0  @Win31 
Purpose Notification that a minimized (iconic) window needs to have the background painted. This mes- 
sage is received if a class icon is defined for the window. If there is no class icon defined (see 
RegisterClass()), WM_ERASEBKGND is sent instead. If this message is processed by the default 
Windows message processing logic in DefWindowProc(), the background of the minimized win- 
dow is painted with the desktop window’s class background brush. 
Parameters 
wParam WORD: Contains the iconic window’s device context. 
lParam DWORD: Not used. . 
WM WM_INITDIALOG | | mWin2.0 mWin3.0 mWin3.l 


Purpose Notification that a dialog box is about to be displayed. This is similar to WM_CREATE messages in 
the main WndProc() function. WM_INITDIALOG is sent every time the dialog is displayed, not 
just when the program starts. WM_INITDIALOG mes offer a good opportunity to initialize 
any data associated with the dialog oe, * 


Parameters __ : : 
wParam : WORD: The ID value of the first control to have the input focus when the dialog box starts. This 
a is usually the first itemwith the WS_! TABSTOP style. 
lParam *  DWORD: If the dialog. box was created with either. CreateDialogIndirectParam(), CreateDialog- 
~~ ParamQ), DialogBoxIndirectParam(), or DialogBoxParam(), this value will hold the dwInit- 
Param data passed when the dialog box.was created. Otherwise (with the normal dialog box 
. definition i in the resource RO file), the (Param value is-not used. 

WM _INITMENU | ae (ms Win2.0 mWin3.0 -mWin31 

Purpose Notification that the user has clicked amain menuitem. This message is sent before the menuis 
accessed. Only one WM_INITMENU message is- generated per access to the menu, no matter how 
many items the e Mouse may click. It-¢ be used a reminder to change menu items (grayed, 

checked, etc.) before the menu selections are vactivated. 

Parameters pe ae 4 = ~~ 

wParam WORD: Contains the menu handle. 

lParam DWORD: Not used. 

WM_INITMENUPOPUP mWin2.0 mWin3.0 mWin3.1 

Purpose Notification that the window is about to display a popup menu. This can be used as a reminder to 
. a popup menu items ea checked, etc.) before the menu selections are activated. 

Parameters ae 

wParam WORD: The handle of the popup menu. 

lParam DWORD: The low-order word contains the index of the popup menu in the main menu. The high- 


order word is nonzero if the popup menu is the system menu, zero otherwise. 
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WM. _KEYDOWN Ls im eWin20. mWin30 mWin3l 
Purpose ’ Notification that a key was pressed. This notification is sent to the window with the input focus as 
: ‘long as the Gir) key was not depressed at the time of the keypress. WM_SYSKEYDOWN messages 
are sent if the Gi) key is down, or if no window has the input focus. SYSKEY messages also cover 
the system functions such as online between windows (GALT)-GaB), (AET)-(ESC), etc). 


wParam WORD: The virtual key cite of the key. See Chapter 7 Keyboard Support, for alist of virtual key — 
codes. 
lParam — DWORD: The contents are encoded as shown in Table 9-21. 
0-15 (low order word) The repeat count. This is the number of times the character was repeated because the user 
Poe heid down a key. 
16-23 0 °° | The keyboard scan code. 
24 : 1 if an extended key, such as a function key or a key on the numeric keypad. 
25-28 . Not available 
29° CO : d if the (air) key was held down when the key was pressed, 0 if not. Always 0 in this case. 
30 —— 1 if the key is down before the message was sent, 0 if not. 
8 1 if the key is being released, 0 if the key is being pressed. 
Table 9-21. The 82-Bit Keyboard Data For WM_KEYUP, WM_KEYDOWN. 
Purpose — Notification that a key was released. This notification is sent to the window with the input focus. 


as long as the (air) key was not depressed at the time of the keypress. WM_SYSKEYUP messages _ 
" are sent if the (att) key is down, or if no window has the input focus. SYSKEY messages also cover 
; the system functions such as switching between windows ((&ir)-(7AB), (ALT)-(ESC), etc). 
Parameters | 


_ wParam WORD: The virtual a code of the key. See Chapter 7, Keyboard Support, for a list of virtual key 
codes. 
‘Param  DWORD: The contents are eee as shown in Table 9-21 in the WM_KEYDOWN description, 
WM _KILLFOCUS | mWin2.0 m@Wind0 mWind1 
Purpose Notification that a window is shod to lose the input focus. If the application is displaying a caret, 
- it should be destroyed at this point. 
Parameters . . 
wParam WORD: Contains the handle of the window thatis about to receive the input focus. Mav be NULL. 
\Param —Sé WORD: Notused. . | | a 
WM_LBUTTONDBLCLK Win2.0 e8Win30 _ @Win31 
Purpose Notification that the user has double-clicked the left mouse button. Only windows that-have a. 
- glass structure that includes the CS_DBLCLKS style will receive these messages. Note that the 
single mouse click message — precedes a double clic message. 
. Parameters . 
“wParam  .— ~WORD: Contains a value reflecting whether several ‘cone were down at the time the message was 


sent. This can by any combination of the binary flags listed in Table 9-22. 
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MK_! CONTROL the CONT ROL re is doin 
MK_LBUTTON The left mouse button is down. 
MK_MBUTTON The center mouse button (if any) is down. 
MK_RBUTTON The right mouse button (if any) is down. 


MK_SHIFT The SHIFT key is down. . 

Table 9-22. Mouse Key Flags. | 

lParam | DWORD: The low-order word contains the X position of the cursor when the button was pressed. 
The Y position is in the high-order word. The coordinates are in pixels, relative to the upper left 
corner of the window. 

WM_LBUTTONDOWN wWin20 mWin30 mWin3l 

Purpose Notification that the user has pressed the left mouse button. 

Parameters 

wParam WORD: Contains a value reflecting whether several keys were down at the time the message was 


sent. This can by any combination of the binary — listed in Table 9-23. 


MK “CONT ROL The CONTROL key is down. 
MK_LBUTTON The left mouse button is down. 
MK_MBUTTON The center mouse button (if any) is down. 
MK_RBUTTON The right mouse buiton (if any) is down. 


MK_SHIFT The SHIFT key is dswn 
Table 9-23. Mouse Key Flags. , 
lParam DWORD: The low-order word contains the X position of the cursor when the button was pressed. 
The Y position is in the high-order word. The coordinates are in pixels, relative to the upper left 

_ corner of the window. | | 
WM_LBUTTONUP BWin2.0 wWind0 wWindl | 
Purpose Notification that the user has released the left mouse button. 
Parameters 
wParam WORD: Contains a value reflecting whether or not several keys were down at the time the mes- 


sage was sent. This can by any combination of the binary flags listed in Table 9-24. 


MK. CONTROL _ The CONTROL key is down. 
MK_LBUTTON The left mouse button is down. _ 
MK_MBUTTON The center mouse button (if any) is down. | 
MK_RBUTTON The right mouse button (f any) is down. 
MK_SHIFT The SHIFT key is down. 


Table 9-24, Mouse Key Flags. 
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iParam — - DWORD: The jow-order word contains the X position of the cursor when the button was pressed. 


The Y position is in the high-order word. The coordinates are in pixels, relative to the upper left- 
corner of the window. = 
WM _MBUTTONDBLCLK | aWin20 Win30 mWin3l 
Purpose | Notification that the user double-clicked the center.mouse button. Only windows that have a 


class structure that,includes the CS_DBLCLKS style will receive these messages. Note that the. 
. single mouse click message always precedes a double-click message. \ 
Parameters . 
wParam WORD: Contains a value reflecting whether several keys were down at the time the message was™ 
sent. This can by any combination of the ais aie in Table 9-25. 


MK_CONTROL The CONTROL key is down. 
MK_LBUTTON The left mouse button is down. 
MK_MBUTTON The center mouse button (if any) is down. 
MK_RBUTTON The right mouse button (if any) is down. 


MK_SHIFT | The SHIFT key is down. 
Table 9-25. -Mouse Key Flags. 
lParam * DWORD: The low-order word contains the X position of the cursor when the button was pressed. 
The Y position is in the high-order word. The coordinates are in pixels, relative to the upper left 
corner of the window. . | 
WM_MBUTTONDOWN Win2.0 ‘@Win3.0 wWin3.1 
Purpose Notification that the user has pressed the center mouse button. oy 
Parameters noe 
wParam WORD: Contains a value reflecting whether or not several keys were down at the time the mes 


sage was sent, This can by any combination of the aha flags listed in Table 9-26. 


MK_CONTROL = The CONTROL key is down. 
MK_LBUTTON The left mouse button is down. 
MK_MBUTTON The center mouse button (if any) is down. 
MK_RBUTTON The right mouse button (if any) is down. 


MK SHIFT The SHIFT key is down. 
Table 9-26. Mouse Key Flags. 
lParam -DWORD: The low-order word contains the X position of the cursor when the button was pressed. — 
The Y position is in the high-order word. The coordinates are in pixels, relative to the upper left 
corner of the window. 
WM_MBUTTONUP : Win2.0 eWin3.0 wWin3.] 


Purpose Notification that the user has released the center mouse button. 
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Parameters 


wParam WORD: Contains a value reflecting whether several keys were down at the time the message was 
’ sent. This can zs any combination of the binary flags listed in Table 9-27. 


MK_CONTROL. The CONTROL aL key’ is down. 
MK_LBUTTON The left mouse button is down. 
MIK-MBUTTON The center mouse button (if any) is down. 
MK-RBUTTON The right mouse button (if any) is down. 


MK_SHIFT The SHIFT key is down. 
Table 9-27. Mouse Key Flags. 
lParam DWORD: The low-order word contains the X position of the cursor when the button was pressed. 
The Y position is in the high-order word. The coordinates are in pixels, relative to the upper left 
corner of the window. 
WM_MDIACTIVATE OWin2.0 mWind0 mWin3l 
Purpose Used to activate and deactivate child windows within a Multiple Document Interface (MDI) win- 


dow. Activation of a MDI child window is similar to a window gaining the input focus. Once acti- 
vated, the child window’s border is highlighted, and all keyboard input is directed to the child. 
When receiving this message, an MDI child frequently changes the frame window menu using the ~ 
WM_MDISETMENU message. 


Syntax . SendMessage (HWND hClient, WM_MDIACTIVATE, WORD,wParam, DWORD lParam) 
Parameters . 

hClient HWND: The window handle of the MDI client or child window. 

wParam WORD: If the application is sending the message to the MDI client window, wParam contains 


the handle of the child window to activate. If the MDI client window is sending this to an MDI 
child window, wParam contains nonzero to activate the child window and zero to deactivate it. 
lParam DWORD: NULL if the application is sending the message to the MDI client window. If the MDI 
: client window message processing function is sending the message to an MDI child window, the 
high-order word contains the handle of the child window being deactivated, and the low-order 
word contains the handle of the child being activated. 


~WM_MDICASCADE OWin2.0 wWin30 mWindl 


Purpose Arranges all of the child windows within the MDI client window in “cascade” format. This ar- 
rangement makes all of the window titles visible. If the frame window is too small, some of the 
child windows may not be visible after cascading. — 


Syntax SendMessage (HWND hClient, WM_ MDICASCADE, WORD peaeanses DWORD /Param) 


Parameters. 
hClient HWND: The window handle of the MDI client window. 
wParam WORD: The cascade flag. No flags are defined under Windows 3.0. Under Windows 3.1, the 
MDITILE_SKIPDISABLED flag prevents disabled MDI child windows from being tiled. nee: 
wise, set to 0. 
[Param DWORD: Not used. Set equal to OL. 
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WM. -MDICREATE | alt - — OWin2.0 .8Wind.0 mWin3.1 
Purpose Creates an MDI child window. This message is sent to the client window to create a new child 
window. The title of the child window name is added to the window menu of the frame window. 
“Syntax -° dwReturned = Sena ceaae (HWND hClient, WM_MDICREATE, WORD wParet, DWORD 
Cane (Param) 
> ‘Returns-.. DWORD. The-MDI child window handle is in the low-order word. The high- order word is NULL. 
: Parameters | 
hClient HWND: The window sande of the MDI client window. . 
_ wParam WORD: Not used. Set equal to 0. 
lParam DWORD: A far pointer to a MDICREATESTRUCT structure. This is defined in WINDOS: H as 


typedef struct tagMDICREATESTRUCT 
wea Ge 


LPSTR 
“LPSTR 
HANDLE 
int 
int 
LONG 
LONG 


szClass; /* class previously registered with. megderennhaes<? */ 


szTitle; /* title string */ 

hOwner; /* instance handle of the owner */ 

X,Y¥?7 /* the X,Y position of the upper Left corner */ 
cx,cy; /* the X, Y wintow size */ 

style; - /* the style; usually 0 for MDI child Windows */ 
LParam; /* app-defined stuff oa 


’ } MDICREATESTRUCT; 
‘ typedef MDICREATESTRUCT FAR * + LPMDICREATESTRUCT; 


If another MDI child window is maximized, it will be restored before the new child window is 
created. The child window receives a WM_CREATE message, with the IpCreateParams field of 
the CREATESTRUCT containing a pointer to the MDICREATESTRUCT data structure data. 


WM _MDIDESTROY a a ee =o OWin20 eWin30 m8 Win3.1 
| Purpose Destroys (removes) an MDI child window: The child window title is removed from the window. : 
. ~ menu of the frame window. 
Syntax SendMessage CAWND nGhent, WM_MDIDESTROY, WORD wParam, DWORD aay 
Parameters 
hClient HWND: The window handle of the MDI client window. 
wParam WORD: The window handle of the MDI child window to destroy. 
‘Param | - DWORD: Not used. Set equal to OL. 
WM _MDIGETACTIVE | OWin2.0 m@Win30 wWin3l 
_ Purpose Obtains the handle of the currently active MDI child window. a - 
Syntax dwReturned = SendMessage (HWND Oe: WM_. MDIGET SU INE: WORD reer. DWORD 
lParam) 
Returns DWORD. The low-order word contains the handle to the active MDI child window. The high-order 
“ad . word contains 1 if the MDI child is maximized, otherwise it contains 0. 
Parameters coca cecal 
hClient HWND: The window handle of the MDI client window, 
wParam _ WORD: Not used. Set equal to 0-- 
lParam DWORD: Not used. Set equal to OL. 
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WM_MDIICONARRANGE OWin2.0 wWin30 mWin31 


Purpose Causes the MDI client window to arrange all minimized MDI child windows at the bottom of the 
. client area. This message has no effect on MDI child windows that are not minimized. 

Syntax SendMessage (HWND hClient, WM_MDIICONARRANGE, WORD wParam, DWORD lParam) 

Parameters 

hClient HWND: The window handle of the MDI client window. 

wParam WORD: Not used. Set equal to 0. 

lParam _- DWORD: Not used. Set equal to OL. 

WM_MDIMAXIMIZE es" OWin20 m@Wind0 mWind. 


Purpose Causes an MDI child window to be maximized. This makes the child window exactly fill the client 
: area of the client (frame) window. Windows automatically places the child window’s system menu... 
“AEE in the frame’s menu bar and adds the child window's title to the frame window.title. 
a - Ifa child window hidden behind the maximized window is activated, the maximized window 
is restored to its previous size, and the newly active window is maximized in its place. 


Syntax . SendMessage (HWND hClient, WM_MDIMAXIMIZE, WORD wParam, DWORD lParam) 
Parameters ~ . 

hClient HWND: The window handle of the MDI client window. 

wParam WORD: The MDI child window handle to be maximized. 

lParam DWORD: Not used. Set equal to OL. 

WM_MDINEXT OWin20 mWin30 mWin3.1 
Purpose _ Activates the next MDI child window. The next window is the one immediately behind the cur- 


rently active window. The currently active window is placed behind all other MDI child windows 
after this message is processed. If the active MDI child window is maximized, the previously 
active window is restored in size, and the newly active window is maximized in its place. 


Syntax SendMessage (HWND hClient, WM_MDINEXT, WORD wParam, DWORD lParam) 

Parameters | 

hClient. HWND: The window handle of the MDI client window. 

wParam WORD: Not used. Set equal to 0. 

lParam DWORD: Not used. Set equal to OL. 

WM_MDIRESTORE OWin20 8Win30 ms Win31 
- Purpose Restores an MDI child window to its previous size. This message is used after a child window has 
be been either minimized or maximized. 

Syntax — SendMessage (HWND hClient, WM_MDIRESTORE, WORD wParam, DWORD lParam) 

Parameters me 

hClient HWND: The window handle of the MDI client window. 

wParam WORD: The handle of the MDI child window to restore. 


lParam. DWORD: Not used. Set equal to OL. 
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WM_MDISETMENU OWin20 mWind0 mWin3l 
Purpose -. Links a menu to the MDI frame window. The MDI child window list is maintained after the new 


menu is installed. (The MDI child window list is a popup menu, maintained eis the MDICLIENT 
window as child windows are created and destroyed.) 


Syntax . = dwkReturned = SendMessage (HWND hClient, WM_ MDISETMENU, WORD wParam, DWORD 


lParam) 
Returns. DWORD, contains a handle (HMENU) to the previous gent window menu that was replaced 
Parameters . 
hClient — ; HWND: The window handle of the MDI client window. 
wParam WORD: Not used. Set equal to 0. 


[Param DWORD: The low-order word contains the handle to the new client window menu, or NULL ‘it 
there is to be no change in the client menu. The high-order word contains the handle to the new 
Windows popup menu, or NULL if there is to be no change in that menu. 


Note | If more than one menu is in use, the MDI application will need to destroy menus before exiting to 
avoid having the menu resource data remain in memory after the application terminates. The 
application should call DrawMenuBar() after any change to a menu. 


WM_MDITILE OWin2.0 mWin3,0 mWin3l 


Purpose Causes an MDI client window to arrange all of its children in tile format. For two or three child 
windows, this is side-by-side, for four child windows, each child occupies one corner of the client 
area, etc. 
Syntax. SendMessage (HWND hClient, WM_MDITILE, WORD wParam, DWORD ee 
Parameters 
hClient == ~~. ~HWND: The window handle of the MDI client window. 


wParam WORD: The cascade sale This is composed of one or two of tue values i in Table 9-28, 


MOITILE. HORIZONTAL Arranges the MDI child windows in a horizontal sequence. 
MDITILE_SKIPDISABLED (Win 3.1) Disabled MDI child windows are not tiled. 
MDITILE_VERTICAL Arranges the MDI child windows in a vertical sequence. 


Table 9-28. WM. MDITILE Flags. 


MDITILE_SKIPDISABLED can be combined with either of the other flags using the C lan- | 
guage binary OR operator (1). 


lParam DWORD: Not used. Set equal to OL. 


WM_MEASUREITEM OWin2.0 mWind0 mWindl 
Purpose Sent to the owner of an owner-redrawn button, list box, combo box, or menu item when the item 


is created. The owner function should fill in the MEASUREITEM data structure pointed to by: 
lParam and return. For list boxes and combo boxes, the message is sent once for each item in the 


list. 
wParam WORD: Not used. 7 
lParam DWORD: A pointer to a MEASUREITEMSTRUCT structure. This is defined in WINDOWS. Has 


330 


9. WINDOWS MESSAGES ¥ 


/* MEASUREITEMSTRUCT for ownerdraw */ 
typedef struct tagMEASUREITEMSTRUCT 


{ - 
WORD CtlType; /* ODT_MENU, ODT_LISTBOX, ODT_COMBOBOX, or ODT_BUTTON */ 
WORD CtlID; /* control id number for List box, combo box or button */ 
WORD itemID; /* the item's id number in the List or combo box */ 
WORD itemWidth; /* these are the values that need to */ 
WORD itemHeight; /* be set to specify the size of the control */ 
DWORD itemData; /* the 32-bit data goes here */ 


} MEASUREITEMSTRUCT; 
typedef MEASUREITEMSTRUCT NEAR *PMEASUREITEMSTRUCT; 
typedef MEASUREITEMSTRUCT FAR *LPMEASUREITEMSTRUCT; 


The itemWidth and itemHeight elements should be set by the owner function before re- 


turning. 
WM_MENUCHAR @Win2.0 mWin3.0 wm Win3.l 
Purpose Informs the application that the user attempted to use a keyboard shortcut for a menu selection 


that did not match any menu item. This provides a way to give more than one keyboard shortcut 
to a single menu item. 


Parameters 

wParam WORD: The ASCII character that the user pressed. 

lParam DWORD: The high-order word contains the menu handle. The low-order word contains either 

MF_POPUP if the menu is a popup menu, or MF_SYSMENU if the menu is the system menu. 

Returns The WndProc() processing this message can return a value to specify what action Windows should 
take. The value is returned in the high-order word of the value returned by WndProc(). This can 
be 0 to ignore the keystroke (default), 1 to tell Windows to close the menu, or 2 to make a differ- 
ent selection. In the last case, the low-order word of the return value should be the menu item 
number to select. 

WM_MENUSELECT Win2.0 g@Win3.0 mWin31 

Purpose Notification that the user has selected a menu item. 

Parameters ; 

wParam WORD: The menu item ID for the selection. If the user selected the caption of a popup menu, 
wParam contains the popup menu ID. The latter is normally ignored. 

lParam DWORD: The low-order word contains a combination of the binary flags listed in Table 9-29. 


Meaning Src? S08 oh eek ee PES 


MF_BITMAP The item is a bitmap. 


MF_CHECKED The item is checked. 

MF_DISABLED The item is disabled. 

MF_GRAYED The item is grayed. 

MF_MOUSESELECT The item was selected with the mouse. 

MF_OWNERDRAW The item is an owner-redrawn menu item. 

MF_POPUP ’ The item contains a popup submenu. : 
MF_SYSMENU The item is in the System menu. In this case, the high-order word is the handle of the menu. 


Table 9-29. WM_MENUSELECT Flags. 
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AVM_MOUSEACTIVATE . | mWin2.0 wWin3.0 Win 3.1 


Purpose Notification that the cursor is in an inactive window and the user clicked a mouse button. A 
parent window will receive this message unless the child window intercepts the message. Nor- 
mally, the child window will pass the message on to DefWindowProc(), which in turn sends it to 
the parent window. The parent window can stop the message processing by returning TRUE when 
the message is received, rather than sending it on via DefWindowProc(). This will stop the child 

_ from being activated. The default action is to activate the child window that was clicked. 


Parameters 

wParam WORD: Contains a handle to the parent window. 

lParam ° DWORD: The mouse message (such as WM_LBUTTONDOWN) is in the high-order word. The low- 
order word contains the mouse hit test. See Appendix B, Useful Macros from Windows, for a list 
of all the hit test codes. 

Returns © _—— The receiving application can pass this message on to the DefWindowProc() function, or return a 


specific value. The returned value must be one of the codes in Table 9-80. 


tlh Meaning. : 
MA-ACTIVATE Activate the window. 
MA_NOACTIVATE Do not activate the window. 
MA_ACTIVATEANDEAT Activate the window, and discard the mouse event. 


MA_NOACTIVATEANDEAT (Win 3.1) Do not activate the window, and discard the mouse event. 
Table 9-30. WM_MOUSEACTIVATE Return Codes. 


If a child window passes the message on to DefWindowProc(), the message is sent on to the 
child's parent window without action or modification. : 


-WM_MOUSEMOVE | mWin2.0 wWin30 mWin3l 


Purpose Notification that the user moved the mouse. 
Parameters" = 
wParam WORD: Contains a value reflecting whether several keys were down at the time the message was 


sent. This can be any combination of the binary flags in Table 9-31. 


MK_CONTROL The CONTROL key is gin 
MK_LBUTTON The left mouse button is down. 
MK_MBUTTON The center mouse button (if any) is down. 
MK_RBUTTON The right mouse button {if any) is down. 
MK_SHIFT The SHIFT key as down. 


Table 9-31. Mouse Key Flags. 
lParam . __ DWORD: The low-order word contains the X position of the cursor when the button was pressed. 


The Y position is in the high-order word. The positions are measured in pixels, from the upper. left : 
corner of the cuntow: 


332 — 


9. WINDOWS MESSAGES _V 


/ . 


WM_MOVE Win2.0 mWin3.0 - mWin31 
Purpose Notification that a window has been moved. 

Parameters 

wParam WORD: Not used. 

lParam DWORD: The low-order word contains the X position of the upper left corner of the client area of 


the window. The Y position is in the high-order word. The location is given in screen coordinates, 
relative to the upper left corner of the screen. 


WM_NCACTIVATE Win2.0  mWin3.0 mWin3.1 


Purpose Notification that the nonclient area of a window needs to be changed to reflect an active or 
inactive state. The default actions (performed by the DefWindowProc() function) draw a gray 
caption bar for an inactive window and a black caption bar for an active one. 


Parameters 


wParam WORD: Nonzero if the icon or caption is active, zero if inactive. 
lParam DWORD: Not used. 
WM_NCCALCSIZE mWin2.0 mWin3.0 mWin3.1 
- Purpose Sent when the size of a window, including the title, border, and caption areas, needs to be recal- 
culated. Normally, this message is passed to DefWindowProc(), which fills in the needed data in 
the RECT data structure. The application program can intercept the message and fill in different 
values. This message is used in applications that draw their own nonclient areas or applications 
that control the sizing of the main window. 
Parameters 
wParam WORD: Not used. . 
lParam DWORD: A far pointer to a RECT data structure. The RECT data contains the screen coordinates 
of the window’s outer rectangle. The application can fill in different values to control the 
nonclient area sizing. 
| , ae 
WM_NCCREATE _  mWin2.0 m8 Win30 mm Win31 
Purpose Notification that Windows is about to create the nonclient area of the window. This message is 
sent prior to WM_CREATE. The default actions of allocating internal memory, initializing scroll 
bars, and setting the window’s text are almost always desirable, so this message is usually passed 
to DefWindowProc(). 
Parameters 
wParam WORD: The window handle of the window being created. 
_ Param DWORD: A far pointer to a CREATESTRUCT data structure. See WM _CREATE for the structure 
‘details. . . 
WM_NCDESTROY . aWin2.0 mWin3.0 mWin3.l 
- Purpose Informs a window that its nonclient area is being destroyed. This message is sent after 
_ WM_DESTROY. The message triggers the release of memory allocated internally for the window 
when it is passed to DefWindowProc(). 
Parameters . a : 
wParam WORD: Not used. 
lParam | DWORD:*Not used. 
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WM_NCHITTEST eWin2.0 e@Win3.0 mWin3J 

Purpose ~ Sent to the window that used GetCapture() to capture all mouse input. The message is sent every 

time the mouse is moved. 

Parameters . 

wParam _ WORD: Not used. 

lParam DWORD: The low-order word contains the X position of the cursor. The Y position is in the high- 

. order word. Screen coordinates are used. 
Note: DefWindowProc() returns the mouse hit test code when processing this message. The hit test 
_ codes are listed in Appendix 2, Mouse Hit Test Codes. 

WM_NCLBUTTONDBLCLK go Win20 = |Win8.0 Wind] 

Purpose Notification that the user double-clicked the left mouse button while the mouse cursor was in the 

nonclient area of the window. 

Parameters 

wParam WORD: Contains the hit test code. See Appendix 2, Mouse Hit Test Codes, for a list. 

lParam _ DWORD: Contains a POINT data structure, which gives the mouse cursor position when the ._ 

mouse button was double-clicked. Mouse cursor locations are always in screen coordinates, with ° 
. 0,0 in the upper left corner. ee 

WM_NCLBUTTONDOWN. ees mWin2.0 Win 3.0 | 8 Win 3.1 

Purpose | Notification that the user pressed the left mouse button while the mouse cursor was in the:non 

client area of the window. 

Parameters | . 

wParam WORD: Contains the hit test code. See Appendix 2, Mouse Hit Test Codes, for the list. 

lParam DWORD: Contains a POINT data structure, which gives the mouse cursor position when the 

mouse button was pressed. Mouse cursor locations are always in. screen coordinates, with 0,0 
being in the upper left corner. 

WM_NCLBUTTONUP — . mWin2.0 @Wind0 sWin3d 

Purpose Notification that the user released the 2 left mouse button while the mouse cursor was in the 

-nonclient area of the window. 

Parameters 

wParam . WORD: Contains the hit test code. See Appendix 2, Mouse Hit Test Codes, for the list 

lParam ~~ . DWORD: Contains a POINT data structure, which gives the mouse cursor position when the 

mouse button was released. Mouse cursor locations are always in screen coordinates, with 0,0 
being in the upper left corner. 

‘WM _NCMBUTTONDBLCLK eWin20 eWind.0 eWind.1 
. Purpose Notification that the user double-clicked the center mouse button while the mouse cursor was in 
_ the nonclient area of the wont 

Parameters. . 

wParam a: WORD: Contains the hit test. code. See Appendix 2, Mouse Hit Test Codes, for the list. 

[Param DWORD: Contains a POINT data structure, which gives the mouse cursor position whenthe 


mouse button was double-clicked. Mouse cursor locations are always in screen coordinates, with 
0,0 in the upper left corner. 
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WM_NCMBUTTONDOWN mWin2.0 Win3.0 we Win3.1 
Purpose Notification that the user has pressed the center mouse button while the mouse cursor was in the 
nonclient area of the window. . 
Parameters , 
wParam WORD: Contains the hit test code. See Appendix 2, Mouse Hit Test Codes, for the list. . 
lParam DWORD: Contains a POINT data structure, which gives the mouse cursor position when the 
mouse button was pressed. Mouse cursor locations are always in screen coordinates, with 0,0 in 
the upper left corner. 
WM_NCMBUTTONUP AWin2.0 oWin3.0 mWin31 
Purpose Notification that the user released the center mouse button while the mouse cursor was in the 
nonclient area of the window. 
Parameters 
wParam WORD: Contains the hit test code. See Appendix 2, Mouse Hit Test Codes, for a list. 
lParam DWORD: Contains a POINT data structure, which gives the mouse cursor position when the 
mouse button was released. Mouse cursor locations are always in screen coordinates, with 0,0 in 
the upper left corner. 
WM_NCMOUSEMOVE aWin2.0 oWin30 Wind! 
Purpose Notification that the mouse has been moved in the nonclient area of the window. 
Parameters 
wParam WORD: Contains the hit test code. See Appendix 2, Mouse Hit Test Codes, for the list. 
lParam. DWORD: Contains a POINT data structure, which gives the mouse cursor position. Mouse cursor 
locations are always in screen coordinates, with 0,0 in the upper left corner. 
WM_NCPAINT Win2.0 oWin3.0 mWin31 
Purpose Notification that the nonclient area of a window needs to be repainted. Most applications just 
pass this on to the DefWindowProc() function, which paints the nonclient area. Custom frames 
__ and caption areas can be created by intercepting this message and painting the area from within 
‘the application code. 
' Parameters 
wParam WORD: Not used. 
“lParam DWORD: Not used. 
WM_NCRBUTTONDBLCLK aWin2.0 eWin3.0 mWin3.1 
Purpose Notification that the user double-clicked the right mouse button while the mouse cursor was in 
the nonclient area of the window. 
Parameters ced + . 
wParam ».. . WORD: Contains the hit test code. See Appendix 2, Mouse Hit Test Codes, for the list. 
lParam ‘ .  DWORD: Contains a POINT data structure, which gives the mouse cursor position when the 


mouse button was double-clicked. Mouse cursor locations are always in screen coordinates, with 
0,0 in the upper left corner. 
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WM_NCRBUTTONDOWN | gg Win2.0 sm Win 3.0 | aw Wind 


Purpose Notification that the user pressed the right mouse button while the mouse cursor was in the 

nonclient area of the window. 

Parameters : 

wParam WORD: Contains the hit test code. See Appendix 2, Mouse Hit Test Codes, for the list. 

lParam ‘DWORD: Contains a POINT data structure, giving the mouse cursor position when the mouse 
button was pressed. Mouse cursor locations are always in screen COOrENES with 0,0 in the 
upper left corner. 

WM_NCRBUTTONUP Win2.0 mWin3.0 mWin3.1 

Purpose Notification that the user released the right mouse button while the mouse cursor was in the 
nonclient area of the window. 

Parameters 

wParam WORD: Contains the hit test code. See Appendix 2, Mouse Hit Test Codes, for the list. 

‘Param DWORD: Contains a POINT data structure, which gives the mouse cursor position when the 
‘mouse button was released. Mouse cursor locations are aways! in screen coordinates, with 0,0 in 
the upper left corner. 

WM_NEXTDLGCTL | | Win2.0 mWin30 wWin3.l 

Purpose Moves the input focus to another child window control within a dialog box. This message should 
be sent with PostMessage(), rather than SendMessage(), to avoid having the anput focus shift 
while the dialog box processes other messages. 

Syntax PostMessage (HWND hDig, WM_NEXTDLGCTL, WORD wParam, DWORD IParam) 

Parameters 

hDig HWND: The handle of the dialog box. 

wParam WORD 

lParam DWORD: The /Param and wParam values work together to specify the action, as shown in Table. 
9-32. 

hControl TRUE hContro! (handle to a child window sal gets the ‘foil focus and gets a dark border. 
FALSE — FALSE Next control with the WS_TABSTOP style gets the input focus and gets a dark border. 


TRUE FALSE Previous control with the WS_TABSTOP style gets the input focus and gets a dark border. 
- Table 9-32. WM_NEXTDLGCTL Settings. | 


WM_NULL — mWin2.0 wWin30 m#Win3.l 


Purpose No action is taken if this is sent or processed by DefWindowProc(). WM_NULL can be used in 
n° _- hook functions to eliminate the action of a message without eliminating the message itself. . 
Parameters . ° P . 
'. wParam WORD: Not used. 


lParam DWORD: Not used. 
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WM. OTHERWINDOWCREATED a : OWin2.0 OWin3.0 Wins. 

Purpose Sent to all overlapped and popup windows running in the system when a new top-level window (a 
. window unowned by any other window) is created’. 

Parameters 

wParam - WORD: The handle of the window being created. — 

lParam DWORD: Not used. 


Related Messages WM_ OTHERWINDOWDESTROYED, WM_CREATE 


WM _OTHERWINDOWDESTROYED OWin2.0 mWin3.0 mWin3.1 


Purpose ~ Sent to all overlapped and popup windows running in the system when a top-level window (a 
window unowned by any other window) is destroyed. 
Parameters So 
wParam WORD: The handle of the window being destroyed. 
[Param -- DWORD: Not used. 


Related Messages WM_OTHERWINDOWCREATED, WM _DESTROY 


WM_PAINT | Bs he mWin2.0 mWin30 mWin3t 

Purpose Notification that the client area of a window needs to be repainted. This message can be forced by 
calling the UpdateWindow() function. It is automatically generated by Windows if the applica- 
tion window is resized or uncovered from beneath other windows. The update region is reset by 


calling BeginPaint(). 
Parameters 
wParam WORD: Not used. 
lParam DWORD: Not used. is 
WM_PAINTCLIPBOARD | @Win2.0 mWin30 sWin3.1 
Purpose _ This message is used by clipboard viewer applications to notify that the viewer data should be 
repainted. The clipboard data must be in the CF_OWNERDISPLAY format for this to occur. 
Parameters 
wParam - WORD: Contains the window handle of the clipboard viewer window. 
lParam _ DWORD: Contains a pointer to a PAINTSTRUCT data structure. This is defined in WINDOWS.H as 
typedef struct tagPAINTSTRUCT 
i ; : 

HDC hdc; /* device context */ 

BOOL fErase; _ ; : 

RECT rcPaint; , /* repaint rectangle */ 

BOOL fRestore; 

BOOL fincUpdate; 

BYTE rgbReserved(16]; 

} PAINTSTRUCT; 

typedef PAINTSTRUCT *PPAINTSTRUCT; - : y 
typedef PAINTSTRUCT: NEAR: *NPPAINTSTRUCT; 
typedef PAINTSTRUCT FAR *LPPAINTSTRUCT; 


The rcPaint element contains a RECT data structure that holds the dimensions of ihe area 
that needs to be repainted. This: can be compared with the most resent dimensions obtained 
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when processing a WM_SIZECLIPBOARD message. The application processing this message will 
need to use GlobalLock() to fix the location of the PAINTSTRUCT data While reading the data 
and will need to use GlobalUnlock() to release the data. 


WM_PAINTICON OWin2.0 wmWin3.0 wWin3l | 


Purpose Notification that a minimized (iconic) window needs to be repainted. This message will only be 
received if the window was created based on a window class containing a class icon. If no class 
icon is defined, the minimized window receives WM_PAINT messages. DefWindowProc() paints 
the icon with the class icon. By intercepting this message, the application program can paint 
directly on the iconized window client area. 


Parameters 


wParam WORD: Not used. 
lParam DWORD: Not used. 
WM_PALETTECHANGED OWin2.0 mWin30 gmWin31 
Purpose Notification that the system color palette has changed. This message is sent to all applications . 
when the active window calls the RealizePalette() function. Inactive windows should call 
RealizePalette() when they receive this message. RealizePalette() minimizes the number of 
color changes shown on inactive windows when the system palette changes. 
Parameters 
wParam WORD: The window handle of the application that changed the system palette. The function 
. calling RealizePalette() can compare this value with its own window handle to avoid an infinite 
loop of RealizePalette() and WM_PALETTECHANGED messages. 
lParam DWORD: Not used. 
WM_PARENTNOTIFY OWin2.0 em Win3,0  eWin3.1 
Purpose Notification to the parent window that a child window is being created, destroyed, or clicked with 
the mouse. This message is received only if the child window was created with the 
~ WM_PARENTNOTIFY style. If the application has children of children, etc., all of the predeces- 
sor windows receive this message if all children have the WM_PARENTNOTIFY style. By default, 
child window controls inside dialog boxes do not.notify their parent windows. 
Parameters ht - 
wParam WORD: The type of notification may be any one of the codes in Table 9-33. 
WM "CREATE The child window is about to be eae 
WM_DESTROY The child window is about to be destroyed. 
WM_LBUTTONDOWN The user clicked the left mouse button over the child window. 
WM_MBUTTONDOWN The user clicked the center mouse button over the child window. 
WM_RBUTTONDOWN _ | The user clicked the right mouse button over the child window. 


Table 9-33. WM_PARENTNOTIFY Codes. 


lParam - DWORD: The low-order word contains the handle of the child window. The high-order word 
- contains the child window ID value, which ¥ was specified as the nents parameter when 
CreateWindow() was called. 
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WM_PASTE . @ Win 2.0 Win3.0  mWin31 

Purpose Copies the text from the clipboard into an edit control. The text is inserted at the current caret 
, position within the edit control. The text in the clipboard is assumed to be in CF_TEXT format. 

Syntax SendMessage (HWND hControl, WM_PASTE, WORD wParam, DWORD /Param) 

Parameters | 

hControl ’  HWND: The window handle of the edit control. 

wParam WORD: Not used. 

[Param DWORD: Not used. 

WM_QUERYDRAGICON Win2.0 mWin3.0  mWin3.l 

Purpose Notification that the user is about to drag (move) a minimized (iconic) window. This message is 


sent only if the window was created with a class structure that does not have a default icon 
defined. Windows will display the default icon cursor when moving a minimized window that does 
not have a class icon. This display has the effect of suddenly changing the icon image, which may 
not be desirable. The application can intercept this message and return a handle to a mono- 
chronie cursor to specify the cursor shape to display. Use LoadCursor() to obtain the cursor 
handle. Return the handle in the low-order word. Return NULL to use the default icon cursor. 


Parameters 

wParam WORD: Not used. 

lParam DWORD: Not used. 

WM_QUERYENDSESSION @ Win 2.0 Win3.0 mi Win3.l 

Purpose Notification that the Windows session is about to be ended. This gives applications a chance to 
save data files before the Windows session is over. The application should return a nonzero value — 
if the application can be shut down, zero if not. The DefWindowProc() returns a nonzero value, 
allowing shutdown to continue. 

Parameters 

wParam WORD: Not used. 

lParam DWORD: Not used. 

WM_QUERYNEWPALETTE TWin2.0 a Wind.0  @ Win3.) 

Purpose Notification that an application is about to receive the input focus. If the application needs to 
realize its logical color palette when it receives the input focus, the window should return a 
nonzero value to this message. The default return value from DefWindowProc() is zero. 

Parameters 

wParam WORD: Not used. 

[Param . DWORD: Not used. 

WM _QUERYOPEN — Win 2.0 Win 3.0m Win3.J 

Purpose Notification that a minimized (iconic) window is about to be restored. This provides a chance for 


the application to refuse to restore the window. This may be appropriate for a small utility, such 
as a clock program, that should always be minimized. The application should return a nonzero 
value if the window can be restored, zero if not. The default returned value from 
DefWindowProc() is nonzero. 
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Parameters. 

wParam ——«._— WORD: Not used. 

lParam. DWORD: Not used. : 

WM_QUIT * mWin20) mWin3.0  mWin3l 

Purpose This is the final message processed by an application. It is generated when the application calls 
PostQuitMessage(). When GetMessage() receives this value in the program’s message loop, it 
returns zero, causing the message loop to be exited and the program to exit. 

Parameters 

wParam WORD: Contains the exit code given in the PostQuitMessage() function call. 

(Param . DWORD: Not used. — 

WM_RBUTTONDBLCLK | aa mw Win20) mm Win38.0) sm Win3! 

Purpose _ Notification that the user has double-clicked the right mouse button. Only windows that have a 

. ©, ,¢lass structure that includes the CS_DBLCLKS style will receive these messages. Note that the: 

b -.. single mouse. lick meses always precede a moun: click message. 

Parameters a oe ami 

wParam WORD: Contains: a value reflecting whether sevsial keys were down at the time the message was 


sent. This can by any combination of the binary flags in Table 9-34. 


MK “CONTROL The CONTROL key is down. 
MK_LBUTTON The left mouse button is down. 

| MK_MBUTTON . The center mouse button (f any) is down. 
MK_RBUTTON _-The right mouse button is down. 
MK_SHIFT The SHIFT key is down. 


Table 9-34. Mouse Flags. 


[Param . DWORD: The low-order word contains theX position of the cursor r when the button was piseed 
The Y position is in the high-order word. The positions are in pixels, from the upper left corner of 
athe window. . . 
| WM. _RBUTTONDOWN | oa 7 i Win2.0 mi Win3.0 Win 3.1 
Purpose =—__Notification that the user pressed the right meu button, = 
Parameters | oe . . 
wParam WORD: Contains a value reflecting whether several keys were down at the time the message was 


sent. This can by any combination of the binary flags in Table 9- a 


MK “CONTROL ~ The CONTROL key is down. 
_ MK_LBUTTON The left mouse button is down... 
~ MK_MBUTTON ' The center mouse button (if any) is down. 
MK-SHIFT 7 The SHIFT key’ is down, 


Table 9-35. Mouse enone 
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lParam DWORD: The low-order word contains the X position of the cursor when the button was pressed. 
The Y position is in the ue order word. The positions are in in pixels, from the upper left corner of 
the window. 
WM_RBUTTONUP | mWin2.0 mWin3.0 mWin31 
Purpose Notification that the user released the right mouse button. 
~ Parameters 8 
wParam WORD: Contains a value reflecting whether several keys were down at the time the message was 


- sent. This can by any combination of the binary flags listed in Table 9-36. 


MK “CONTROL The CONTROL key is down. 
MK_LBUTTON The left mouse button is down. 
MK_MBUTTON The center mouse button (if any) is down. 


MK_SHIFT The SHIFT key is down. 
Table 9-86. Mouse Flags. 
lParam DWORD: The low-order word contains the X position of the cursor when the button was pressed. 
The Y position is in the high-order word. The positions are in pixels, from the upper left corner of 
the window. 
WM _RENDERALLFORMATS mWin20 mWin30  mWindl 
Purpose ’ Notification to the owner of one or more clipboard formats that the application program is exit- 


‘ing. This message is received if the application uses delayed rendering of clipboard data (waiting 
until the data is needed to add it to the clipboard). The application receiving this message should 
put the appropriate data in allocated global memory blocks and call setChpboaedDataQ) te for each 
format of clipboard. See Chapter 17, The Clipboard, for details. 


Parameters 
wParam. WORD: Not used. 
[Param — DWORD: Not used. 
WM_RENDERFORMAT eWin2.0 wWin30 mWin31 
Purpose _ Notification to the owner of the clipboard that data should be put in the clipboard in the specified | 
, format. This message is received if the application uses delayed rendering of clipboard data 
(waiting until the data is needed to add it to the clipboard). See Chapter 17, The Clipboard, for 
| details. 
Parameters . 
wParam . WORD: The format of the clipboard requesting data. The clipboard formats are listed in Chapter 
. _* 17, The Clipboard, and in the SetClipboardData() function description. 
[Param ~ DWORD: Not used. ~ - . | 
WM_SETCURSOR ; | wWin2.0 mWin30  mWin3.1 
Purpose _ Notification that the mouse cursor is moving within a window. This message provides a chance to 


change the mouse shape depending on where it is. If the cursor is over a child window, Def- 
_ WindowProc() passes the WM_SETCURSOR message on to the parent window's message pro- 
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cessing function before acting on it. This gives the parent window's message processing function 

a chance to determine all the cursor shapes for the application. If the parent also passes the 

message to DefWindowProc(), the default actions are to change the cursor shape back to the 

normal arrow cursor when the cursor leaves the client area of the window. This causes a change 

in cursor shape if the window was created based on a class structure with a cursor shape other 
"than the standard arrow. 


Parameters 

wParam _ WORD: The handle of the window that contains the cursor. 

lParam DWORD: The moue hit test code is in the low-order word, and the mouse message (such as 
WM_LBUTTONDOWN) is in the high-order word. See Appendix 2, Mouse Hit Test Codes, for the 
list of all mouse hit test codes. . 

WM_SETFOCUS Win2.0 mwWin3.0 mWin3.1 

Purpose . Notification that a window has gained the input focus. At this point, all keyboard input will start 
going to the window. If the window uses a caret, this is a good point to display the caret so that the 
user will know where the next keyboard input will show up. 

Parameters 

wParam WORD: Not used. 

lParam ~ DWORD: Not used. 

WM_SETFONT — OWin 2.0 mWin30 Wind! 

Purpose Used to change the font used in dialog box controls. This message should be sent to each control 

. that changes fonts when the dialog box function receives a WM_INITDIALOG message. _ 

Syntax -+  SendMessage (HWND kControl, WM_SETFONT, WORD wParam, DWORD lParam) . 

Parameters me 

hControl . HWND: The window handle of the child window control (button, list box, etc.). 

wParam -WORD: A handle to the font. NULL for the system (default) font. 

(Param DWORD: TRUE if the control should be redrawn immediately, FALSE if not. Use /Param equal to 
TRUE if you are changing the font during the execution of the dialog box. Setting the /Param 
value FALSE (zero) saves time if the dialog box function is processing a WM_INITDLALOG mes- 
sage. 

Comments __ Windows will send the WM_SETFONT message to the dialog box message function if the dialog 
box was created with the DS_SETFONT style. This is only possible if the CreateDialogIndirect(), 
CreateDialogIndirectParam(), DialogBoxIndirect(), or DialogBoxIndirectParam() functions 

. were used to create the dialog box. 

WM_SETREDRAW Win2.0 mWin3.0 mWin3.1 

Purpose _ Sent to a list box and to combo box controls prior to adding or deleting a number of items. By 
turning redrawing off during the changes, the changes occur faster and without a lot of distract- 
ing action within the list box area of the control. The redraw status i is then set back to the normal 

’ ON state at the end of the changes. 

Syntax SendMessage (HWND hControl, WA_SETREDRAW, WORD wParam, DWORD lParam) 

Parameters | , 

hControl HWND: The window handle of the child window control (list box, combo box). 
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wParam WORD: Nonzero to turn on redrawing in the control. Zero to turn off redrawing in the control. 
lParam DWORD: Not used. 

WM_SETTEXT . mWin2.0 wWin3.0 mWin3.] 
Purpose Used to change the title or text of a window. For button controls, this changes the button’s text. 


For edit controls and combo boxes, it changes the edit control text. For parent, child, and popup 
windows, the window caption is changed. Sending this message is equivalent to calling the 
SetWindowText() function. 


Syntax dwkcturned = SendMessage (HWND AControl, WM_SETTEXT, WORD wParam, DWORD 
lParam) ; 

Returns DWORD, normally ignored. Returns CB_ERRSPACE if there is not enough room in the edit con- 
trol of the combo box to hold the string. Returns CB_ERR if the combo box does not have an edit — 
control. 

Parameters 

hControl HWND: The window handle of the child window control (button, combo box, etc.). 

wParam WORD: Not used. 

[Param — DWORD: A pointer to a null-terminated string containing the new text. 

WM_SHOWWINDOW Win2.0  mWin3.0  aWin3.1 

Purpose Notification that a window is to be either hidden or shown. This message occurs when the 


ShowWindow() function is called, or when an overlapped or popup window is maximized, re- 
stored, minimized, or opened. The DefWindowProc() function hides or shows the window when it 
processes this message. 


- Parameters 

wParam WORD: Nonzero if the window is being shown, zero if it is being hidden. 

[Param DWORD: Zero ifa call to ShowWindow() was the reason for the message. SW_PARENTCLOSING 
if a parent window is closing, or a popup window is being hidden. SV_PARENTOPENING if a 
parent window is being displayed, or a popup wit ‘ow is being shown. 

WM_SIZE Win2.0 mWin3.0 mf Win3l 

Purpose Notification that the size of a window has changed. Applications usually process this message to 
keep track of how big the clienta area of the window is. 

Parameters . 

wParam WORD: Contains one of the values in Table 9-37. 


SIZEFULLSCREEN The window has been maximized. 
SIZE!ICONIC The window has been minimized (made iconic). 
SIZENORMAL The window has been resized. . 


SIZEZOOMHIDE __ Sent to all popup windows when another window has been maximized. 
SIZEZOOMSHOW _ Sent to all popup windows when another window has been restored to its previous size. 


Table 9-37. WM_SIZE Codes. 
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lParam... DWORD: The low-order word contains the width of the window's client area. The high-order word 
contains the height. Both are in pixels. 


WM_SIZECLIPBOARD eWin2.0 mWin30 mWin3.l 


Purpose, Notification that the clipboard viewer application has changed size. This will occur only if the 
wee ae oe clipboard contains a data handle for the CF_ OWNERDISPLAY format. This message will be sent 
with a null rectangle (values 0,0,0,0) when the er viewer is about to be destroyed. 


Parameters 


wParam _ WORD: The window handle of the clipboard vit viewer. 
lParam DWORD: A pointer to a RECT data structure that contains the area the cpbar viewer r should 
. . paint. 
WM_SPOOLERSTATUS a OWin2.0 mWin30 mWin3.l 
Purpose Notification from the Print MAnABEE iat a job has been added or subtracted from the printer 
_. queue. 3} : 
. Parameters 
wParam WORD: Equal toSP_JOBSTATUS. _ ; 
lParam DWORD: The low-order word contains the number of jobs i in the eprint queue. The high order 
| word i is not oe pte 
WM. SYSCHAR. i Bon thin ab ae He Win 2.0) mm Win3.0 i Win3.1 
Purpose o8,, This is the equivalent ofa WM_CHAR message, except that it is generated by TranslateMessage() 
ens in the application’s message loop when a WM_ SYSKEYUP or WM _SYSKEYDOWN message is 
processed. SYSKEY messages are sent if the (at) key is down or if no window has the input 
focus. SYSKEY messages alee’ ¢ cover the system functions such as switching between windows 
(D-Gap) aD) GD: (ESO) ED) ete). 
Parameters 
wParam: ~~ WORD: The ASCII value of the key pressed. | 
lParam DWORD: The 32-bit keyboard data for the key, coded : as shown i in 1 Table 9- 38. 
0-15 (low order word)... .. The ceed count. This is ther number of ti times the characte was epee because t the user’ 
held a key down. 
16-23 The keyboard scan code. 
24 1 if an extended key, such as a function key or a key on the numeric keypad. 
25-28 Not available. i das 
“29 "1 if the @aH key was held down ol the key.was pressed, Oifnot. This i is called the “context 
code.” 
30 1 if the key is down before the message was sent, 0 if not. 
31 _ if the key is being released, 0 if the key is being pressed. 


pute 9-38. 82-Bit Coded Keyboard Data. 


Note If bit 29 is zero, the message can be passed to TranslateAccelerator() within the application’ s 
message loop. This allows the accelerator keys to be used with the active window even if it does 
not have the input focus. 
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WM_SYSCOLORCHANGE wWin2.0 mWin30 mWin3.l 


Purpose . Notification that one or more of the system colors has changed. This message is sent to ali top- 
level windows when a system color is changed. Applications that use the system colors to create 
objects (pens, brushes, etc.) should delete those items and create new ones using the current 
system colors. This message is followed by a WM_PAINT message. 


Parameters bys 

wParam WORD: Not used. _ 

[Param DWORD: Not used. 

WM_SYSCOMMAND i mWin20 mWin30 mWin3.1 

Purpose Notification that the user has selected a system menu command (the menu that appears if the 

. button at the top left corner of a window is clicked), or that the minimize or maximize buttons in 
the upper right corner of the window are pressed. Note that the system menu can be modified by 
the application. Menu items added to the system menu generate WM_SYSCOMMAND messages, 
i1iot WM_COMMAND. Do not pass added menu options on the system menu to DefWindowProc(). 
Just return after the processing of the message is complete. 
Parameters = 


wParam ~ WORD: One of the values listed in Table 9-39. 


SC_CLOSE __, Close the window. er ; 

SC_HOTKEY (Win 3.1) Activates a window associated with the application-specified hot key. The low-order word of 
{Param contains the window handle of the window to activate. 

SC_HSCROLL Scroll horizontally. 

SC_KEYMENU  _ Menu retrieved via a keystroke. 


SC_MAXIMIZE (or SC_ZOOM) | Maximize the window. 
~§C_MINIMIZE (or SC_ICON) Minimize the window. 


SC_MOUSEMENU Menu retrieved via a mouse click. 
SC_MOVE Move the window. 

SC_NEXTWINDOW ~ Move to the next window. 
SC_PREVWINDOW ; Move to the previous window. 
SC_RESTORE Restore the window to its previous size. 


SC_SCREENSAVE (Win 3.1) Executes the screen-save application specified in the desktop section of the Windows 3.1 
Control Panel. - 


SC. SIZE Resize the window. 


SC_TASKLIST (Win 3.1) Executes or activates the Windows task manager application. 
‘SC_VSCROLL Scroll the window vertically. 
Table 9-39. WM_SYSCOMMAND Values. . . | a 
lParam DWORD: If the mouse was used to select a system menu couunand, the low-order word contains 
_ the mouse X position, and the high-order word contains the Y position. Otherwise, [Param is not 
used, —— . 
Notes All the SC_ values are defined in WINDOWS.H all be above 0x000F in value. This is because Windows 


_ uses the lower four bits internally. Be sure to AND (&) the wParam value with 0xFFFO before 
testing the value to see which SC_ option was selected. 
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WM__ SYSDEADCHAR | . mWin2.0 wWin3.0 eWin3J 


Purpose Notification of a system dead character. This occurs when a WM_SYSKEYDOWN or 
WM. SYSKEYUP message is processed by TranslateMessage() in the window message loop, for a 
system keystroke on a non-English keyboard that is using an accented character. 


Parameters os 

wParam WORD: Contains the dead-key value, per the keyboard language definition in use. 

[Param DWORD: The low-order word contains the repeat count. The high- “order word contains the auto- 
repeat count. These values usually can be ignored. 

WM_SYSKEYDOWN wWin2.0 mWin30 me Win3.1 

Purpose Notification that the user pressed a key while holding down the key. It also occurs when no 
window has the input focus. WM_SYSKEYDOWN is then sent to the active window. Bit 29 of 
lParam can be used to distinguish between these two cases. This message is processed by 
TranslateMessage() in the appaceon: s message 1000, which generates a WM_SYSCHAR mes- 
sage. 

Parameters 4 

wParam WORD: The virtual key code of the key pressed.. 

[Param DWORD: The 32-bit encoded data for the keypress. See Table 9-388 under WM_SYSCHAR for the 

es ’ meaning of each bit. 

Note’ If bit 29 is zero, the message can be passed to TranslateAccelerator() within the application’s 

message loop. This allows accelerator keys to be used with the active window even if it does not 
- have the input focus. 
. WM_SYSKEYUP . , mWin2.0 t&Win3.0 Win 3.1 

-Purpose Notification that the user released a key while holding down the key. It also occurs when no 
window has the input focus. WM_SYSKEYDOWN is then sent to the active window. Bit 29 of 
[Param can be used to distinguish between these two cases. This message is processed by 
TranslateMessage() in the application’s message loop, which generates a WM_SYSCHAR mes- 
sage. - 

Parameters 

wParam WORD: The virtual key code of the key pressed. 

lParam DWORD: The 32-bit encoded data for the keypress. See Table 9-38 under WM_SYSCHAR for the 
meaning of each bit. 

Note | If bit 29 is zero, the message can be passed to ansiateAcoalorator® within the application’s 
message loop. This allows accelerator keys to be used with the active window even if it does not 
have the input focus. . 

WM_TIMECHANGE = mWin2.0 mWin3.0  mWin3.1 

Purpose Notification that the system clock has been changed. This message should be sent to all top-level 
windows if the application changes the clock. 

Syntax: . _ dwReturned = SendMessage (0xFFFF, WM_TIMECHANGE, 0, OL) ; 

Parameters The parameters should be set as shown, so that the message is sent to all top-level windows 


ts = OxFFFF does this). 
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WM_TIMER a BWin2.0 @Win380 wWin3.] 
Purpose Notification that one of the timers set with the SetTimer() function has passed its time interval. 
Parameters . . . 
wParam WORD: The timer ID value, used as the 2/DEvent parameter when SetTimer() was called. 
[Param DWORD: Normally NULL. If the value is nonzero, /Param is a procedure-instance handle to a 
function set as the lpTimerFunc parameter when SetTimer() was called. In this case, Windows 
executes the timer function directly, rather than sending the WM_TIMER message to the 
window's message processing function. 
WM_UNDO gWin2.0 mWin30 mWin3.l 
Purpose Copies the text from the clipboard to the edit control’s client area. This eliminates the effect of 
a WM_CUT message. The clipboard contents are assumed to be in CF_TEXT format. 
Syntax SendMessage (HWND hControl, WM_UNDO, WORD wParam, DWORD (Param) 
Parameters oa 
hControl HWND: The window handle of the edit control. 
wParam WORD: Not used. Set equal to 0. 
lParam DWORD: Not used. Set equal to OL. 
WM_USER @Win2.0 Win 3.0 Win 3.1 
Purpose Values of WM_USER and above, up to 0x7FFF, can be used by an application for messages defined 
by the application. This is a convenient way for the independent window processing functions of 
the different child and popup windows to communicate. Most programmers define the new mes- 
sages for their application in the application’s header file: 
#define NEWMESSAGE (WM_USER + 1) 
Hde fine SECONDMESSAGE (WM_USER + 2) 
_ If messages are being sent between different applications, WM_USER message coding is not 
~ saved, as different programs can use the same code. for different meanings. Instead, generate a 
system-wide unique message using RegisterWindowMessage(). Note that Windows defines a 
number of child window control messages as WM_USER + a value. If you need to use WM_USER 
+ messages with a child window control (perhaps a subclassed control), be sure the added value 
is large enough that it does not overlap those defined in WINDOWS.H. WM_USER + 200, ete. 
should be fine. 
Parameters 
wParam . WORN: Can have any meaning useful to the application, limited to 16-bits. 
lParam DWORD: Can have any meaning useful to the application, limited to 32-bits. 
WM_VKEYTOITEM Win2.0 mWin3.0 sWin3.1 
Purpose Notification that the user pressed a key while a list box had the input focus. The list box must 
have been created with the LBS_WANTKEYBOARDINPUT style to receive this message. This 
message allows the application to provide keyboard shortcuts to select list box items. 
Parameters 
wParam WORD: Contains the virtual key code for the key i See Chapter 7 » Keyboard Support, for 
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a list of all virtual key codes: 
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lParam. . > DWORD: The low-order window contains the window handle of the list box. The high-order word 
. 7 contains the current selection index. 
Returns The message processing function should return the faites of the item to select. Return ( 0 for the 


first item. To let the list box process the keystroke in the default manner, return -1. To stop all 
processing of the keyboard input to the list box, return “2, 


WM_ VSCROLL “a igitte = sm Win2.0 sm Win3.0 mw Win31 
Purpose Notification that the user has adjusted a a vertical scroll bar. 
Parameters 
wParam WORD: One of the codes in Table 9-40.: 

SB_BOTTOM Carcetedl , the or bar has t the ein ne and the G5) (END) eit is pressed. Not generated by 

: mouse actions. 

SB_ENDSCROLL Sent when the scroll activity stops. 

SB_LINEDOWN Clicked the arrow on the left. 

SB_LINEUP | Clicked the arrow on the right. | | 

SB_PAGEDOWN Clicked the area of the scroll bar between the left arrow and the thumb. 

-SB_PAGEUP Clicked the area of the scroll bar between the right arrow and the thumb. 
SB_THUMBPOSITION | - The message passes the position of the thumb as the low-order word of Param. 
SB_THUMBTRACK ~The thumb is being dragged. The current position is passed as the low-order word of Param. 
SB_TOP Generated if the scroll bar has the inpit tease and the (OME) (HOME) key is pressed. Not generated by 

mouse actions. 


Table 9-40. Scroll Bar Codes. 


Windows documentation suggests that SB_BOTTOM and SB_TOP values are also sent. These 
.. values are not detected with child window scroll bar controls. 
lParam. - DWORD: The high-order word contains the window handle of the seit bar. If the scroll bar is ._ 
a attached to the boundary of a popup window, the high-order value is not used. The "-order word — 
contains the thumb position if either the SB_THUMBPOSITION or SB _ THUMB: RACK value for 
wParam is passed. 


WM_VSCROLLCLIPBOARD |  gWin2.0  wWin30 mWin3.1 


Purpose Used with the CF_OWNERDISPLAY format of data type for the clipboard, used by clipboard 
viewer programs. The message indicates that the clipboard viewer vertical scroll bar me been 
used. . 
Parameters 
wParam ~ WORD: Contains a handle to the clipboard viewer program. 


lParam DWORD: The low-order word contains one of the scroll bar codes shown in Table 9-40, as used in 
WM_VSCROLL messages. The high-order word contains the thumb position if the SB_THUMB-. 
POSITION or SB_THUMBTRACK value is passed in the low-order word. Otherwise, the high- 

order word is not used. , 
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WM_WININICHANGE mWin2.0 mWin3.0 mWin3.l 


Purpose 


Syntax 


Parameters 
wParam 


lParam 


Notification that the WIN.INI file has been changed. Any program that modifies WIN.INI should 
send this message to all top-level windows, per the syntax example. The hWnd parameter is set 
equal to OxFFFF to send a message to all top-level windows. Any program receiving this message 
can check whether the section changed (lParam value) applies to the operation of the program. 
If so, the application can re-initialize after reading that section from WIN.INI. 


SendMessage (0xFFFF, WM_WININICHANGE, WORD wParam, DWORD lParam) 


WORD: Not used. Set equal to 0. 


DWORD: A pointer to a null-terminated character string that contains the WIN.INI section name 
that has been changed. The square brackets used in WIN. INI to show section names should NOT 
be included in this string. Although not officially supported, some applications will send this 
message with /Param set equal to NULL. In this case, the receiving application has no choice but 
to check every relevant section of WIN.INI and re-initialize. 
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In the past, programmers had to continually modify and add to their programs as new printers, video displays, and 
other hardware entered the market. In most cases, these updates distracted from the goal of improving the real 
functionality of the software. One of the major advantages to using the Windows environment is that Windows deals 
with the hardware for you. A well-designed Windows program will continue to function exactly as intended when new 
computer and printer hardware are introduced. 


The Device Context 


The basic tool that Windows uses to insulate your program from the “real-world” hardware is called a device context, 
or DC. ‘The DC amounts to about 800 bytes of information that Windows maintains about an output device, such as a 
video screen or a printer. Instead of sending output directly to the hardware, your program sends it to the DC, and 
then Windows sends it to the hardware. As an example, consider the steps necessary to output a string to the client 
area of a window. First, declare a variable to hold a handle to the device context. This is just an unsigned integer that 
Windows uses to keep track of which DC is active. (The HDC data type is defined in WINDOWS.H.) 


HDC hDC ; /* a handle to the device context */ 


Second, retrieve a handle to the client area's device context with the GetDC() function. 
hDC = GetDC ChWnd) ; /* get a handle to the window's client area DC */ 


Finally, output the text to the device context, and release the device context. Releasing the DC is important, as 
Windows will not allow access to the device context by another program until it is released. 

TextOut (hDC, 0, 0, "Text Output To Client Area.", 25) ; 
ReleaseDC (hWnd, hDC) ; ; 

This is not too complicated, but there is more going on kere than you might expect. We did not specify the charac- 
ter font to use, what color to draw the text, how big to make the letters, etc. All of these parameters were based on the 
default values stored in the device context. To expand on this example, let’s output the same string again. This time 
we will pick a different font and make the color of the text bright red. The code now looks like 


HDC hDC ; 


hDC = GetDC ChWnd) ; 

SelectObject (hDC, GetStockObject CANSI_VAR_FONT)) ; 
SetTextColor (hDC, R&B (255, 0, 0)) ; 

TextOut (hDC, 0, 0, “Text Output To Client Area.", 25) ; 
ReleaseDC (hWnd, hDC) ; : 


Two new lines were added. SelectObject() was used to select a new font into the device context. In this case, one 
of the six stock fonts was loaded. The SetTextColor() function modified one of the device context settings, changing 
the text color to red. A handy macro RGB() defined in WINDOWS.H was used to create the 32-bit color value needed 
for SetTextColor() by specifying the red, green, and blue elements of the color. The result of these changes is that this 
- time TextOutQ) writes the output with red letters, using the ANSI_VAR_FONT character font. A wide range of other 
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changes are possible for a device context. You can select different pens, brushes, fonts, and colors. You can also scale 
the device context in different ways to increase the hardware independence of your program. 


Handling WM_PAINT Messages 


You will not use the GetDCQ) and ReleaseDC() functions to retrieve and release the window’s client area DC when 
you process WM_PAINT messages. Windows provides two specialized functions to handle this situation: BeginPaint() 
and EndPaint(). Windows assumes that you will want to speed up your program’s screen refresh logic by only painting 
the areas that need repainting. Windows updates a PAINTSTRUCT data structure when the WM_PAINT message is 
sent. The PAINTSTRUCT structure is defined in WINDOWS.H as follows: 


typedef struct tagPAINTSTRUCT.i.PAINTSTRUCT; 
{ 


HDC hde; 

BOOL fErase; 

RECT rcPaint; 

BOOL fRestore; 

BOOL fIncUpdate; 

BYTE rgbReservedLl[16]; 
} PAINTSTRUCT; 


typedef PAINTSTRUCT *PPAINTSTRUCT; = 
typedef PAINTSTRUCT NEAR *NPPAINTSTRUCT; 
typedef PAINTSTRUCT FAR *LPPAINTSTRUCT; 


The rcPaint element of the structure contains the rectangle that defines the sinallest rectangle that covers all of 
the client area that needs to be repainted. You can also use the hdc element of the PAINTSTRUCT as a quick way to 
get the client area DC. You do not have to be efficient in repainting just the rectangle that needs updating. You can 
repaint the whole client area when you get a WM_PAINT message. Most programs do this to simplify their painting 
logic. Only the parts of the client area that are in the refresh rectangle will actually be repainted, even though the 
output functions may specify painting in the entire area. If the screen updates become too slow, put some more logic 
‘ into the processing of WM_PAINT messages to reduce the amount of repainting that needs to be done. This subject 
will be covered in the next Chapter, Painting the Screen. 


Selecting Objects into a Device Context 

At any given time, a device context will have one pen to draw line. vith, one brush to fill areas with, one font to type 
letters in, and a series of other values to control how the device context behaves. If you want to use a different font, 
you need to select it into the device context. This makes it available the next time you want to do some text output. 
Selecting a new font does not redraw text on the window’s client area. New text appears only ifyou select the new font, 
and then use it to output text with a function like TextOut(). The following example switches from one font to another 
for the output of two separate lines. 


HDC hoc ;. 


hDC = GetDC (hWnd) ; 

SelectObject (hDC, GetStockObject COEM_FIXED_FONT)) ; 
TextOut ChDC, 0, 0, "Text Output With OEM Font.", 24) ; 
SelectObject (hDC, GetStockObject CANSI_VAR_FONT)) ; 
TextOut ChDC, 0, 20, "Text Output With ANSI Font". 26) ; 
ReleaseDC Chiind, hDC) ; 

The first line is typed using the OEM _FIXED_FONT, while the second one is typed with the ANSI_VAR_FONT. 
Both lines will be visible in the client area when this code fragment is executed. So far, we have used only stock 
objects, that are always available in Windows. Stock objects are not deleted after use. Most of the time you will ned 
to create new pens, brushes, and fonts. These objects take up memory and need to be deleted when not needed. 

Here are a few rules in dealing with device contexts: 


“ok Only five device contexts can be open at any one time. 


2. Donot attempt to delete stock objects. They are the objects listed under the GetStockObject() function, such 
as OEM_FIXED_FONT. 
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3. Do not delete objects that are selected into the device context. Always select a new object, or a stoc. object, 
into the device context to displace the object you created. Then delete it when the object is no longer tied to 
the device context, delete it.. 


Another way to assure that you do not delete an object that. is selected into the doves context is to release the 
device context before deleting the objects it has been using. 


Private Device Contexts 


In the previous examples, the handle to the window’ s client area device contexts was retrieved right before it was 
needed and released right after its use. This is the normal case. Using this type of logic makes the program as memory 
efficient as possible, by only tying up the device context during the periods when the program is generating output. 
The cost of this memory efficiency is program speed. Every time the program wants to output, it must fetch the device 
context handle, modify the default DC settings as needed, do the output, and finally release the DC. All of this takes 
time. 

An alternative way for z a program to deal with the client area device context is to keep its own private copy. Thisi is 
done by specifying the CS_OWNDC class style in the class definition for the window. The top. of the eae RING: 
tion will include a line like . eee 


wodelase: style = CS_HREDRAW | CS_ _VREDRAW | cs_. OWNDC; 


With this class style, the device context exists for the life of the window. The program still uses GetDCd A . 
retrieve a handle to the device context. There is no need to call ReleaseDC() after the device context is used 
(ReleaseDC() will not do anything in this case.) Having a private device context is also convenient for programs that 
make changes to the device context settings. Changes such as new text colors, pens, and brushes, remain in effect 
until they are changed again or the program exits. 

You should choose between private and public device contexts based on the type of application you are writing. If 
the program only makes limited use of the device contex or seldom changes the default settings, use a public device 
context to save memory. If the program makes heavy use of the device context, use a private DC to speed up execution 
and simplify the program. 


Saving a Device Context. 


In some applications, you may find yourself repeatedly switching between two or three common sets of device context 
settings. For example, you may be using a combination of one font, color, background mode, etc. to paint the fixed part 
of the client area and using another combination of font and colors for the parts the user can change. A convenient. 
way to code applications like this is to create separate device contexts and save them with the SaveDC() function. 

SaveDC() saves the settings in a “context stack,” where they can be recovered at any time by calling RestoreDC(). 
Calling RestoreDC() does not remove the saved copy of the DC from the stack, so you can switch to these settings any 
number of times. The saved device contexts will be removed with the stack when the application terminates. . 


Mapping Modes 


One of the default assumptions a device context starts with i is the coordinate system for mapping points on the device. 
The default coordinates put the origin (the point with.X = 0 and Y = 0) at the top left corner.X values increase to the 
right, and Y values i increase downward. The measurement units are ee A aa is one dot on the screen, or one dot 
on the printer. 

The default coordinates are acceptable if you only write to the screen. If you also ail to write to thi niintoe you 
have problems. One pixel on a laser printer is a lot smaller than one pixel on the'screen. The result is that the output 
that fills up the window on the screen ends up the size of a postage stamp when printed. We want Windows to take 
care of hardware dependencies, so something better has to be done. The answer lies in using a better coordinate 
system than just pixels. Windows calls changing the coordinate system “setting a mapping mode.” The SetMapMode() 
function does the work. The default mapping mode is called MM_TEXT. There are five other mapping modes that 
scale output. Size can be measured in English, metric, or printer’s units: Ateape): Table it llists: Be nike: ‘size ma 
ping modes. 
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Mapping Mode . Meaning 


MM_HIENGLISH Each logical unit is 0.001 inch. X increases to the right. Y increases upward. 
MM_HIMETRIC Each logical unit is 0.01 millimeter. X increases to the right. Y increases upward. 
MM_LOENGLISH — Each logical unit is 0.01 inch. X increases to the right. Y increases upward. 
MM_LOMETRIC Each logical unit is 0.1 millimeter. X increases to the right. Y increases upward. 


MM_TEXT This is the default mapping mode. Each unit equals one pixel. X increases to the right. Y increases 
downward. - 
MM_TWIPS Each logical unit is 1/20 point, or 1/1440 of an inch. X increases to the right. Y increases upward. 


Table 10-1. Fixed Size Mapping Modes. 


The coordinate system units are referred to as “logical units,” as they have meaning only with respect to the 
mapping mode in use. After you have changed the mapping mode, measurements within the device context are based 
on the new system of units, For example, calling TextOut() with the coordinates 10,10 puts the string at the top left 
corner of the client area using the default MM_TEXT mapping mode. If you switch to MM_LOMETRIC, the 10, 10 point 
is | mm to the right and 1 mm above the bottom left corner. The text will end up hidden under the window's border! 
Windows does its best to miake the logical units match real measurements in inches and millimeteres. It does a good 
job with printers, but can be significantly off with video displays. This discrepancy is because Windows has no way of 
knowing what size monitor you are using. 

Another use of a coordinate system is to allow you to shrink or expand graphics by changing the coordinate 
system, rather than by changing the graphics logic. Windows provides two mapping modes for this purpose, MM_ISO# 
TROPIC and MM_ANISOTROPIC. Table 10-2 lists the modes that can be scaled. 


‘Mapping Mode Meaning 


MM_ISOTROPIC _ Arbitrary scaling of the axes, but the X and Y scaling must be the same. Use SetWindowExt( ) 
and SetViewportExt() to set the orientation and scaling. 


MM_ANISOTROPIC This is the most flexible system of units. Either axis can have any scaling factor. Use 
SetWindowExt( ) and SetViewportExt() to set the orientation and scaling. 


Table 10-2. Mapping Modes that Can Be Scaled. 


The MM_ANISOTROPIC mode generally is used for programs that want to distort the graphics displayed in the 
client area to always match the size of the window. MM_ISOTROPIC is used to shrink and expand graphics, without 
distorting the image. Windows uses a rather obscure method to scale these two coordinate systems. Rather than use 
floating point numbers to describe how much to ratio the logical units to the device's pixels, Windows uses two sets of 
integers. One set is called the “window extent,” and the other set is called the “viewport extent.” For example, to scale 
the logical coordinates to be twice the pixel (or “device”) units, you would use the following two function calls: 
SetWindowExt (hDC, 1, 1) ; . 

SetViewportExt ChOC, 2, 2) ; 

You.can also reverse the direction of either of the axes by making the signs of the scaling integers different. For 
example, to scale the logical ccordinates to be 1/10 pixel and have the Y axis increase se upward, use 
SetWindowExt (hDC, 10, 10) ; 

SetViewportExt Choc, 1, -1)'; 

: You can use scaleable coordinates in programs that output to the printer. You will need to adjust the scaling of the 
printer’s device context depending on the resolution of the printer. The function GetDeviceCaps() is handy here, as 

you can use it to find out the horizontal and vertical resolution of the printer. One final bit of flexibility with logical 

coordinate systems is the ability to move the origin. This is a good way to implement scrolling of a graphics display. 

Instead of recalculating where everything should be after the image is scrolled, just change the location of the origin 

and repaint. Windows overkills on this, by giving you two different ways to move the origin. Normally, you will use 
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either SetViewportOrg() or SetWindowOrg(). If you use 
both, be aware that the “viewport” origin is an offset from 
the “window” origin. You can end up with some complex 
- Offsets-from-offsets if you use both functions to move the 
origin. 


Font = ANSI FIXED FONT 


Font = ANSI_VAR_FONT 


DEVI CE DEFAULT F ONT 
Font = OEM_FI XED_FONT 


) Font = SYSTEM_FONT 
Font = SYSTEM_FIXED_FONT 


Fonts 


Windows provides six stock fonts that are always avail- 
able. Figure 10-1 shows what they look like on a VGA dis- 
play. The stock fonts can be fetched at any time using 
the GetStockObject() function, and then SelectObject() 
to add the font to the device context. 

Windows also supports importing new fonts. Fonts 
are defined in files with the .FON extension. Some are 
provided with Windows, and additional fonts can be pur- 
chased from third parties. The .FON files typically define a font at certain sizes and with a limited number of styles 
(italics, bold, underline, etc.). A problem you may run into is that the printer supports a particular font, but it is not 
defined for the screen device context. Windows provides the powerful CreateFont() function to interpolate new fonts 
based on the information in a font file. These estimated fonts are called “logical fonts.” Windows will synthesize a new 
font size or an italic style, even if the size or style is not included in the .FON file. These synthesized fonts tend to be 
~ lower quality than fonts explicitly defined in the font file. 

When scaling fonts, , you will need to understand the system of measurements used to describe a character. Figure 
10-2 shows the names of each measurement. The GetTextMetrics() function returns a pointer to a structure that 
contains all of these values for the current font of a device context. 

It should be no surprise that Windows provides a wide range of related support 
for formatting text. Justification of text to fit a space, adding space between charac- 
ters, changing the background color, and graying the characters are all directly 
supported. 


Font = 


| ‘Figure 1 0-1. Stock Fonts. 


External Leading 


Printer Support. 


Sending output to the printer is almost identical to sending it to the screen. The 
program must get a handle to the printer’s device context. Output is then sent to 
that DC, rather than to the screen’s DC. All of the normal output functions, such as _ 
TextOut() and LineTo(), work for output to a printer, assuming that the printer 
supports graphics. Of cours :, the mapping mode needs to be considered if you want 
to avoid having all of the graphics squished into the upper left corner of the page. 
There are a few differences between printer output and screen output. To get the 
handle to the printer’s device context, use the CreateDC() function instead of GetDC(). Before you can use 
CreateDC(), you will need to find the name of the printer driver ona? active in Windows. Windows writes a line i in 
the WIN.INI file something like — 


Penices PCL I HP Paaeriets HPPCL,LPT1: 


when a printer is selected with the Install or Control Panel applications. The GetProfileString() function provides a 
quick way to read in this string and pass the parameters to CreateDC(). 

When you have the printer’s device context, there are a few extra commands (such as form feeds) for printers that 
have no. equivalent with video displays. Windows provides the Escape() function to send these specialized messages. 
A minimal program fragment for sending a text string to the printer is shown in Listing 10- EB 


o> eting 10-1. Minimal Printer Support 


HDC hDC ; 
char 


Figure 10-2. Text Dimension 
(Metrics ) 


eepeintad C64], *szDriver, Secbevice, *szOutput ; 
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GetProfileString ("Windows", “device”, "", szPrinter, 64) ; 
szDevice = strtok (szPrinter, ",") ; 

szDriver = strtok (NULL, ",") ; 

szOutput = strtok (NULL, ",") ; 

hDC = CreateDC (szDriver, szDevice, szOutput, NULL) ; 

if (Escape (hDC, STARTDOC, 4, "Test", NULL) > 0) 

{ 


TextOut Choc, 10, 10, “Output is on the printer.", 25) ; 
Escape (hDC, NEWFRAME, NULL, NULL, NULL) ; 
Escape (hDC, ENDDOC, NULL, NULL, NULL) ; 

} 

DeleteDC ChDC) ; 


The handy C compiler library function strtok() (string token) is used to divide the device data found in WIN.INI 
to match the fields expected by CreateDC(). The Escape() function sends the STARTDOC message to start printing 
and the ENDDOC message to end printing. The NEWFRAME message causes the page to be ejected. Printer output 
automatically invokes the printer spooler application if the spooler has been selected when the printer was installed. 
If the user has chosen not to use the spooler, the commands and data are sent directly to the printer. 

The simple example shown in Listing 10-1 is suitable only for small print jobs. For larger jobs, you will want to 
provide a way for the user to stop a print job that is in progress. It is also nice to put a dialog box up on the screen to 
show that printing is going on and to provide the “cancel” button. These fairly basic printer support items can become 
a little involved. Remember that Windows programs take control of the system until they choose to release control, 
usually via the GetMessage() function. For our printer abort function, we want Windows to simultaneously send data 
to the printer and monitor a dialog box to see if the user has clicked the cancel button. As you may have guessed, this 
‘ takes some working with Windows message processing logic. 

The heart of the printer “abort” logic is a special call to the Escape() finclion called SETABORTPROC. This 
function informs Windows of the procedure-instance address of a little message processing function that you build 
into the program. Windows periodically sends messages to the “abort” procedure during printing. This gives the pro- 
- gram a chance to stop printing when one of these messages is being processed. To give you an example of how this is 
done, we will expand the previous printing example to include a dialog box with a button for cancelling the print job, 
and an “abort” procedure for processing messages during printing and possibly cancelling the print job. The program's 
definition file (see Listing 10-2) includes two extra exported functions, the “abort” procedure n name and the dialog box 
procedure. 


> Listing 10-2. Printing Example Including an Abort Procedure 


NAME generic 
DESCRIPTION ‘windows printing example' 
EXETYPE . WINDOWS 
STUB "WINSTUB.EXE' 
CODE PRELOAD MOVEABLE 
DATA PRELOAD MOVEABLE MULTIPLE 
HEAPSIZE 1024 
STACKSIZE 5010 
EXPORTS WndProc 
PrintStopDig 
PrintAbort 


The header-file contains the function prototypes for these functions. 


/* generic.h | xf 
#define IDM_DOIT 1 /* menu item id values */ 
define IDM_QUIT 2 
/* global variables */ : 
int ghInstance ; ; 
char gszAppName C) = "generic" ; 
/* function prototypes */ 
Long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 
BOOL FAR PASCAL PrintStopdlg CHWND hDlg, unsigned iMessage, WORD wParam, 
LONG LParam) ; 
BOOL FAR PASCAL PrintAbort CHDC hdePrinter, int node) 3 
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The resource ‘RC file includes the definition of the dialog box that will be displayed while printing is occurring. 


/* generic.r */ 

#include <windows.h> 

#include “generic.h" ok : 
generic ICON generic.ico $e : , 
generic MENU 


BEGIN : ts it 

MENUITEM “&Do It!" IDM_DOIT 
MENUITEM “&Quit", IDM_QUIT 

END 

PrintStop DIALOG 50, 50, 110, 50 


STYLE WS_POPUP | WS —VISIBLE | WS_CAPTION | DS_ MODAL FRAME 

FONT 10, "Helv" _ 

CAPTION “Printer:Active” 

BEGIN | Te dae sate a Ce 

CTEXT Tee "Click Button To Stop", -1, 0, 10, 110, 12 
DEFPUSHBUTTON | ' "Cancel", PSOne RE? 30, 30, 40, 12, WS_GROUP 

END : us i ee Pe 


The WinMain() function for this example | is identical to the GENERIC epplicallon:t in Chapter 1, and i is not re- 
printed. The rest of the C program is as follows: 


HWND ghblgPrintAbort ; ~. ; . /* global variables */ 
BOOL _ gbPrintAbort a Poy 
Long FAR PASCAL WndProc CHWND hWnd, inetoned iMessage, WORD. erarene ‘LONG lParam). 
{ : os on th ; pic athen 
HDC . hpe ; . 
‘ char ar a pe szPrinter. (641, “*szDriver, *szDevice, *szOutput ; 
-FARPROC ae Ts EP EMEA OED ES? (pfnabortPrint ne 
int Pe mae 3. Bee 
2 A switch oeseegey. Bt oe /* process windows messages +f 
oes S ee é toa. Y ve : sf A 7 : 
a case WM_ COMMAND: Pe: /* process menu items */ 
switch (wParam) Se 
C 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
GetProfileString ("Windows", "device", "", 


_ . szPrinter, 64) ; re a 
“szDevice = strtok (szPrinter, " 5 
szDriver = strtok (NULL, ", My: 
sz0utput = strtok (NULL, ",") ; 


hDC = CreateDC (szDriver, S2device, szOutput, NULL) ; 


EnableWindow (hWnd, FALSE) : /* disable main window */ 
gbPrintAbort = FALSE ; = 
/* show the dialog box */ 
LpfnPrintDlg = MakeProcInstance “CPrintStopDlg, 
ghiInstance) ; 
ghDlgPrintAbort = CreateDialog (ghInstance, 
“PrintStop", hwnd, LpfnPrintDlg) ; 
/* turn on the abort proc */ 
UpfnabortPrint = : MakeProcInstance (PrintAbort, 
= ghInstance) ; 
Escape (hDC, SETABORTPROC, 0, 
CLPSTR) bLpfnAbortPrint, NULL) ; 


if (Escape (hDC, STARTDOC, 4, "Test", NULL) > 0) 


{ : 
TextOut Choc, 10, 10, _ ‘ 
“Output is on the printer.", 25) ; 
Escape ChDC, NEWFRAME, NULL, NULL, NULL) ; 
: Escape (hDdC, ENDDOC, NULL, NULL, NULL) ; 
} 


else ‘ ' 7* print error of some sort */' 
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Escape (hOC, ENDDOC, NULL, NULL, NULL) ; 
Reneagseas ChWnd, "Could not activate printer", 
: : “Printer” Error", MB_ICONHAND | MB_OK) ; 
} 
DestroyWindow (ghDlgPrintAbort) :/* kill diated box */ 
i : EnableWindow (hWnd, TRUE) ; /*® enable main window */ 
; SetFocus ChwWnd) ; 
FreeProcinstance (lipfnPrintDlg) ; 
; FreeProcinstance stminaepsenine?: ; 
DeleteDC (hDC) ; 


break 
‘case IDM QUIT: /* send ‘ena of. application message */ 
DestroyWindow ChWnd) ; : 
; break ; 
} ; 
break ; 
case WM_DESTROY: - /* stop application */ 
_ PostQuitNessage (0) ; ic 
break ; 7 
default: /* default windows message processing */ 


- peturn DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} : te ash, 


return (OL) ; 


BOOL FAR PASCAL PrintStopDlg CHUND pola? unsigned, iHessage, WORD uFanan, 
LONG lParam) 


{ 
if CiMessage == WH_COMMAND) 
{ 
gbPrintAbort = TRUE ; 
return CTRUE)D ; 
} 
else s 
return CFALSE) ; 
} 


BOOL FAR PASCAL PrintAbort CHDC hdcPrinter, int nCode) 
{ . 


MSG msg ; : 
while (!gbPrintAbort && PeekNessage (&msg, NULL, 0, 0, PH_REMOVE)) 
: if (!IsDialogMessage (ghDlLgPrintAbort, &msg)) 
: TranslateMessage (&msg) ; . 
DispatchMessage (&msg) ; 
‘ } 


return (!gbPrintAbort) ; 


Note that the “abort” procedure is basically a message loop. Messages from any window, including the dialog box 
window displayed while printing is going on, pass through this loop. The key to aborting the printing job is the global 
variable gbPrintAbort. It is set to FALSE before printing starts. If the button in-the dialog box is activated, 
gbPrintAbort is set to TRUE. This setting is detected the next time a message passes through the “abort” procedure, 
and the printing job i is cancelled. 


The Printer Device Driver 


Although Windows shields you from needing to deal directly with the printer hardware, there are a few situations 
where it is necessary. For example, you may need to determine the size of the paper or the number of paper bins, the 
printer is using to switch from portrait mode to landscape mode. 
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_ When you install a printer under the Windows Control Panel application, a file with the extension .DRV is added 
to the Windows system directory. This file is called a “driver.” Drivers are actually small DLLs (dynamic link libraries, 
explained in Chapter 28). The printer supplier generally writes the driver program, based on the guidelines provided 
by Microsoft. The driver contains all of the code needed to translate the Windows output data into printer-specific 
commands. The driver will also contain the code needed to generate a printer setup dialog box. This is where those 

’ dialog boxes come from that allow you to change from portrait to landscape mode, pick paper sizes, etc. 

Prior to Windows 3.1, the primary way to deal with the device driver was via the Escape() function. A long series 
of commands were supported using Escape() to change and determine printer information. With Windows 3.1, most of — 
the Escape() functions are no longer supported, or are at least discouraged. Several more elegant functions that make 
dealing with the device driver considerably simpler replaced them. 

The key function for working with a printer device driver under Windows 3.1 is ExtDeviceMode(). This function is 
not defined in WINDOWS.H, although a prototype is included in the DRIVINIT.H file which is included with the Win- 
dows SDK. ExtDeviceMode() does not show up in WINDOWS.H because it is not part of Windows—it is part of the 
printer driver. To access ExtDeviceMode() you must load the driver file using LoadLibrary(), and obtain the 
ExtDeviceMode() function's address using GetProcAddress(). These are DLL functions, and they are explained more 
fully in Chapter 28, Dynamic Link Libraries. ExtDeviceMode() is the function that an application calls to cause the 
driver to produce the printer setup dialog box.i.printer setup dialog box. 

ExtDeviceMode() uses a specialized data structure called DEVMODE to store printer specific data. This struc- 
ture is also defined in the DRIVINIT.H file. ExtDeviceMode() will determine the current printer. settings and write the 
data to the DEVMODE structure. This data can be modified to change the printer device context during a print job. 
The ResetDC() function passes the changes in the DEVMODE structure to the driver. The pevieetapaniitie) func- 
tion is also provided as a quick way to determine which features a printer supports. 


\ 


Text and Device Context Function Summary 
Table 10-3 summarizes the device context and text output functions. ‘The detailed function descriptions are in the ~ 


next section. 
= \ ; 
_ AddFontResource . _ Loads a font resource from 4 file into the system. 
CreateDC : Creates a device context to a physical device, such as a priter 
CreateFont . Creates a logical font, ready to belused i in text output. ae 
CreateFontindirect  - - Identical to CreateFont( ), except that the alee e is bas to the function via a 
LOGFONT data structure. ss 
CreatelC : ~ “Retrieves a device context for’ a ee device, but oy for information purposes. 
DeleteDC Deletes a device context created with CreateDC{ ) CompatibleDC( ), or CreatelC(). 
DeviceCapabiiities . - Determines the capabilities of a device, such as. a. ong (Win 3.1) 
DPtoLP . Converts from device points to logical points 
* DrawText . Formats a ea string to fit within the bounds of a rectangle. 
EnumFonts Finds (enumerates) all of the fonts available on a given device. 
_ Escape Sends special information to a device, such as a printer. 
_ ExtDeviceMode _ Determines or modifies the initialization data for a printer. Displays a dialog box for modi the 
’ printer settings. (Win 3.1) 
ExtTextOut . ‘ _ Output of text within.a rectangular area, with separate control over the spacing between each 
Beta ay, ata aa Seah tes, « character. ate ies 
GetBkColor She Determines the current background color for a device cc context, 
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GetBkMode 
GetCharWidth 

GetDC 

GetDCOrg 
GetDeviceCaps 
GetMapMode 
GetSystemMetrics 
GetTabbedTextExtent 
GetTextAlign 
GetTextCharacterExtra 
GetTextColor 
GetTextExtent 
GetTextFace 
GetTextMetrics 
GetViewportExt 
GetViewportOrg 


GetWindowDC 
GetWindowExt 
GetWindowOrg 


GrayString 
LPtoDP 
OffsetViewportOrg 
ReleaseDC 
RemoveFontResource 
ResetDC 
RestoreDC 
SaveDC 

_ ScaleViewportExt 
ScaleWindowExt 
SetBkColor 
SetBkMode 
SetMapMode 
SetMapperFlags 


SetTextAlign . 
SetTextCharacterExtra 
SetTextColor 
SetTextJustification 
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Determines the current background painting mode for a device context. 
Determines the width of one or more characters in a font. 

Retrieves a handle to the device context for the client area of a window. 
Determines the screen coordinates for the logical origin of the device context. 
Determines the capabilities of a device. 

Determines the mapping mode in use by a device context. 

Retrieves the dimensions of different window items on the video display. 
Determines the logical dimensions of a string containing tab characters. 
Determines the text alignment settings of a device context. 

Determines the amount of extra character spacing defined for a device context. 
Retrieves the text color setting for a device context. 

Determines the length of a string when output to a device context. 

Retrieves the name of the current typeface. 

Retrieves basic data about the font currently selected for a device context. 
Used with GetWindowExt( ) to determine the scaling of the device context. 


Used with GetWindowOrq{ ) to determine the location of the origin of the logical coordinate 
system of a device context. - 


Retrieves the device context for the entire window. 
Used with GetViewportExt() to determine the scaling of the device context. 


Used with GetViewportOrg( ) to determine the cant of the origin of the logical coordinate 
system of a device context. 


Draws grayed text or a grayed bitmap at the given location. _ 

Converts a point from logical coordinates to device coordinates. 

Changes the X,Y offset of the logical coordinate system origin. 

Frees the device context. 

Removes a font from the system and frees all memory associated with the font. 
Updates a printer device context. (Win 3.1) 

Restores an old device context saved with SaveDC(). 

Saves a device context for future use. 

Changes the scaling of the logical coordinate system for a device context. 


| Changes the scaling of the logical coordinate system for a device context. 
Sets the color of the background surrounding each character, dashed line, or hatched brush. ~ 


Changes the background painting mode. 
Changes the mapping mode for a device context. 


Adjusts how CreateFont( ) and CreateFontindirect{ ) adjust for font dimensions outside ofthose 


specified in the font data. 

Changes the text alignment for a device context. 

Adds additional space between characters of a device context. 
Changes the text color for a device context. | 

Justifies a string prior to using TextGut() for output. 
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Table 10-3. continued 
Function. 


-Purpose - 


SetViewportExt 


SetViewportOrg 
SetWindowExt 


SetWindowOrg 
TabbedTextOut 
TextOut 
wsprintf 
wvsprintf 


Used with Seti indowExt() to set the ecuine of the logical coordinate Ssaiiw with the 
MM_ISOTROPIC and MM_ANISOTROPIC mapping modes. 

Changes the origin of the coordinate system used for text and graphics locations on a delice. 
Used with SetViewportExt() to set the scaling of the logical coordinate system with the 


’ MM_ISOTROPIC and MM_ANISOTROPIC mapping modes. 


‘Changes the location of the origin of the device context. 

Outputs a text string, expanding all tab characters. 

Outputs a character string at a location on the selected device context. 
Formats text output to a character buffer. 

Formats text output to a character buffer. 


Table 10-8. Text and Device Context Function Summary. 


Text and Device Context Function Descriptions 


ADDF ONTRESOURCE Win2.0 eWin3.0 Win3.l 

Purpose Loads a font resource from a file into the system. 

Syntax int AddFontResource(LPSTR lpFilename); . 

Description The function normally is used to load a font directly from a disk file. It can also be used to load a 
font referenced in the program’s resource .RC file. 

Uses Once loaded, the font is available to all applications. It is not necessary to use this function to 
load the system fonts provided with Windows, unless they have been moved to a directory that 
Windows does not search on startup. — 

Returns The number of fonts loaded. Returns zero if no fonts were loaded, usually meaning that the font 
file or resource was not found. 

See Also RemoveFontResource(), FindResource() 

Parameters 

lpFilename LPSTR: A far pointer to a null-terminated character string containing the font file name. This. 
should be a complete DOS file name including the dizectory path and the “.FON” file extension. 
Alternatively, lpFilename can contain a handle to a font resource e loaded a as part of the resource 
.RC file. The resource file should include a line like 

number FONT ; script.fon 

The FindResource() function is then used to obtain the handle to the font. The handle becomes 
the low-order word of lpFtlename. The high-order word must be zero. 

Related Messages WM_FONTCHANGE should be sent to all top-level windows after a font is loaded or removed. This 
makes the new font’s availability known to all programs running on the system. 

Example This example shows a font file called “script.fon” being loaded at the start of the program and 


removed at the end. SendMessage() is used to notify all other top-level programs of the font’s 
presence. By setting the first parameter in SendMessage() equal to -1, all top-level windows re- 
ceive the message. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
£ 


int nFontLoad ; 
switch (iMessage) a . [*® process windows messages */ 
rf ; : 
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case WM_CREATE: /* bring in the font file .*/ 
nFontLoad = AddFontResource ((LPSTR) "script.fon") ; 
if C!nFontioad) 
MessageBox (hWnd, "Could not load font.", 
MB_ ICONHAND | MB_OK) ; 
/* tell other apps */ 
WM_FONTCHANGE, 0, OL) > 


"Warning", 


else ; 
SendMessage (-1, 
break ; 


case WM_COMMAND: /* process menu items */ 


/* other program lines here */ 


} 


break ; 
case WM_ DESTROY: /* stop application */. 

RemoveFontResource ((LPSTR) “script. fon") : 

SendMNessage (-1, WM_FONTCHANGE, 0, OL) ; 

PostQuitMessage (0) ; 

break ; 
default: 


/* remove font */ 
/* tell apps */ 


/* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 


return COL) ; 


} 


CRrEATEDC 


Purpose 
Include File 
Syntax 


Description 


Uses 


Returns 
See Also 


Parameters 
lpDriverName 


lpDeviceName 
lpOutput 


lpInitData 


/* size of a device name string */ 
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Creates a device context to a physical device, such as a printer. 


<drivinit.h> 
HDC CreateDC(LPSTR lpDriverName, LPSTR lpDeviceName, LPSTR Re ronne LPSTR | 


-lpInitData), 


This is the first step in preparing to send the device graphics data such as text or graphics ob- 


. jects. 


Normally used to create a device context for a printer. In this case, the parameters for the printer 
are fetched from the WIN.INI file using GetProfileString(). The function is also used to get the 
device context of the screen (the hardware screen, not. a window’s client area). To do this, set 
lpDriverName equal to “DISPLAY,” and the other parameters equal.to NULL. This function | 
should be used carefully, as it allows an application to draw anywhere on the screen, not just — 
within the window’s boundaries. Normally, you will use GetDCQ) and BeginPaint() to get a device 
context to a window on the'screen. 


HDC, a device context for the device. Returns NULL on error. 
DeleteDCQ), GetProfileString(), ExtDeviceMode(), DeviceCapabilities() 


LPSTR:. A pointer to a null-terminated string containing the DOS file name of the printer driver. 
The driver file is loaded when a new printer is installed under Windows. Example: “PCL / HP 
LaserJet.” This is the first parameter on the WIN.INI line that starts with “device=.” 

LPSTR: A pointer to a null-terminated string containing the device name. Example: “HPPCL.” 


This is the second parameter on the WIN. INI line that starts with “device=. ” The parameters are 
separated by commas, 


LPSTR: A pointer to a null-terminated string containing the output file or device. Example: 
“LPT1:.” This is the third parameter on the WIN.INI line that starts with “device=.” The param- 


- eters are separated by commas. 


LPDEVMODE: A pointer to a DEVMODE data structure. This structure can be initialized by call- 
ing the ExtDeviceMode() function. Set to NULL to use the default initialization data for the de- 


_ Vice specified by the user in the Control Panel application. The DEVMODE structure is defined in 


DRIVINIT.H as follows: 
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H#define CCHDEVICENAME 32 


typedef struct _devicemode { 


char dmbeviceNameCCCHDEVICENAME]; /* device name string */ 

WORD dmSpecVersion; /* driver specification ver. eg. 0x300 */ 
WORD Gaby ververs eng /*® OEM dirver version number */ 

WORD dmSize; /* size of DEVMODE structure */ 

WORD dmDriverExtra; /* number of bytes following DEVMODE data */ 


DWORD dmFields; : /* bitfield for which of the following dm */ 
5 . /* values are supported. Bit 0 jis one if */ 
/* dmOrientation is supported, etc. */ 
short dmOrientation;- /* DMORIENT_PORTRAIT or DMORIENT_LANDSCAPE */ 
short dmPaperSize; /* DMPAPER_LETTER, DM_PAPER_LEGAL, DM_PAPER_A4 */ 
/* DMPAPER_CSCHEET, DMPAPER_DSCHEET, DMPAPER_ESHEET, DMPAPER_ENV_9 */ 
/* DMPAPER_ENV_10, DMPAPER_ENV_11, DMPAPER_ENV_12, DMPAPER_ENV_14 */ 


short dmPaperLength; /* overrides dmPaperSize, in mm/10 */ 
short dmPaperWidth; ; /* overrides dmPaperSize, in mm/10 */ 
short dmScale; | /* page is scaled by dmScate/100 */ 

short dmCopies; /* number of copies supported */ 

short dmDefaultSource; /* Default paper bin */ 

short dmPrintQuality; /* DMRES_HIGH, DMRES_MEDIUM, DMRES_LOW, */ 
: /* or DMRES_DRAFT */ 

short dmColor; /* DMCOLOR_COLOR or DMCOLOR_MONOCHRCME */ 
short dmDuplex; /* DMDUP_SIMPLEX, DMDUP_HORIZONTAL, */ 


7* or DMDUP_VERTICAL */ 
BYTE dmDriverData EdmDriverExtral] ; /* 0 or more bytes of extra data */ - 
} DEVMODE; 


typedef DEVMODE.* PDEVMODE, NEAR * NPDEVMODE, FAR * LPDEVMODE; 


Example Here the program writes a single line of text to the printer when the user clicks the “Do It!” menu 
' item. The printer information is pulled from WIN.INI using GetProfileString(). The string is 
parsed with the compiler library function strtok(), to break out the device name, driver name, 
and output device name. CreateDC() is used to create the device context for the printer. The © 
Escape() function is used to send the minimal printer codes necessary to start and stop a print 
job. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{- 


HDC hDC ; 
char. szPrinter C643, *szDriver, *szDevice, *szoutput ; 
switch (iMessage) /* process windows messages */ 
{ : 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 

GetProfileString Windows" , “device”, "", 
szPrinter, 64) ; 

szDevice = strtok (szPrinter, weed os 

szDriver = strtok (NULL, ",") ; 

szOutput = strtok (NULL, ",") 3 

hDC = CreatedC ce2Dr very. szDevice, 
szOutput, NULL) ; 

if (Escape (hDC, STARTDOC, 4, "Test", NULL)) 

{ 


Textout Choc, 10, 10, ; 

. “Output 4s on the printer.", 25) 
Escape (hDC, NEWFRAME, NULL, NULL, NULL) 
Escape (hDC, ENDDOC, NULL, NULL, NULL) ; 


we Ne 


} 
Deletedc Choc) ; An 
. break ; 
case IDM_QUIT: /* send end oF application message x] 
pee oveindey Chuind) ; 
break ; 
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3 

break ; ! 
case WM_DESTROY: /* stop application */ 

PostQuitMessage (0) ; 

break 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return COL) ; 


} 


CREATEF ONT 


Purpose 


Syntax 


Description 


Uses 


Returns 
See Also 


Parameters 
nHeight 


nWidth — 
nEscapement 


nOrientation 


nWeight 


cltalie. 


BYTE: TRUE to specify italic characters, FALSE (zero) for normal. 


m@Win2.0 mWin30 wmWind.! 
Creates a logical font, ready to be used in text output. The font is the closest match to the given 
parameters and the font data available. 


HFONT CreateFont(int nHeight, int nWidth, int nEscapement, int nOrientation, int nWeight, 
BYTE cltalic, BYTE cUnderline, BYTE cStrikeOut, BYTE cCharSet, BYTE cOutputPrecision, 
BYTE cClipPrecision, BYTE cQuality, BYTE cPitchAndFamily, LPSTR lpFacename), 


Logical fonts are interpolations between existing font data to create new fonts that approximate 


. the font requested. This allows a font to be displayed on the screen with sizes and bold or italic 


characteristics that may be supported by the printer, but not defined in a .FON file. CreateFont() 
makes the best use it can of loaded font resources before creating a logical font. Any missing data 
is interpolated between existing fonts. Because of this, you can create fonts with sizes and styles 
that do not exist as font resources. The quality of the font will deteriorate as you get farther from 
the resource data. , 


Generally used when a program has only one font to create. CreateFont() has more parameters 
than any other function in Windows. In many cases, the CreateFontIndirect() function is easier 
to use because you load the data ahead of time in a LOGFONT structure and have only the pointer 
to the structure to pass to the function. Both CreateFont() and CreateFontIndirect() can be used 
to do “tricks” with fonts, such as upside-down characters, characters that ale upwards or to the 
left, etc. ‘ 


HFONT, a handle to the font created. This is the handle you use with SelectObject() to make the 
font available for output onto the device context with functions such as TextOut(). 


CreateFontIndirect(), SelectObject(), TextOut(), AddFontResource() 


int: The desired height of the characters, including internal leading and excluding external lead- 
ing. Set equal to zero for the default size. To set the ascent size, rather than the total height, 
make this value negative. The absolute value will then be used to set the ascent size. See Figure 
10-2 for a diagram of the ascent size of a character. 


int: The desired width of the characters. Normally set to 0, which allows Windows to match the 
width to the height. Positive values force a width, changing the character’s aspect ratio. 


int: Specifies the orientation of the next character output relative to the previous one in tenths of 
a degree. Normally, set to 0, Set to 900 to have all the characters go upward from the first charac- 
ter, 1800 to write backwards, or 2700 to write each character from the top down. 


~ int: Specifies how much the character should be rotated when output in tenths of a degree. Set to 


900 to have all the characters lying on their backs, 1800 for upside-down writing, etc. 


int: Sets the line thickness of each character. Only two values are supported in Windows 3.0. 
FW_NORMAL == 400 for normal characters and FW_BOLD == 700 for boldface. WINDOWS.H 
has eight other sizes defined, but these end up rounded to either the 400 or 700 weight. 
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cUnderline 
cStrikeOut 
cCharSet 


BYTE: TRUE to specify underlined characters, FALSE (zero) for normal. 
BYTE: TRUE to specify characters with a line through the center, FALSE (zero) for normal. 


BYTE: The character set of the fent. This can be either ANSI_CHARSET, SYMBOL_CHARSET, 
OEM_CHARSET, or (with Japanese versions of Windows) SHIFTJiS_CHARSET. 


cOutputPrecision BYTE: This field is not yet implemented in the 3.0 version of Windows. Set equal to 


cClipPrecision 


cQuality’ 


OUT_DEFAULT_PRECIS for now to be compatible with future releases of Windows. . 


BYTE: This field is not yet implemented in the 3.0 version of Windows. Set equal to 
CLIP_DEFAULT_PRECIS for now to be compatible with future releases of Windows. 


 BYTE:. Can be either DRAFT_QUALITY, PROOF_QUALITY, or DEFAULT QUALITY. 


PROOF_QUALITY forces the closest match to the loaded font data, which may change the font - 
size if the specified size is not available. 


cPitchAndFamily . BYTE: Two values combined with the C language binary oF aperaies (I). The two low-order bytes 


lpFacename 


Example 


specify the font pitch. This can be 

DEFAULT_ PITCH, FIXED PITCH or VARIABLE _. PITCH 

The four high-order bytes specify the font family. This can be any of the following: 
FF_ DECORATIVE, FF_DONTCARE, FF_ MODERN, FF SCRIPT, or FF SWISS. 


LPSTR: A pointer to a null-terminated string that specifies the name of the typeface. The maxi- 
mum length of the name is LF_FACESIZE, ten is pened in eyo: H as es alshaiaiabel 
can be used within the program to  Feeasse=rr = 5 

find the names of all available fonts. 


This example, which is illustrated in 
Figure 10-3, creates a script font 24 
by 16 units in size and uses it to 
print some text on the window's 


client area. Figure 10-8. CreateFont() Example. 
tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ te oe eee | a oh Se 7 re 
HFONT -hFont ; , : 
oe (iMessage) "/* process windows gesdeaes 47 


case WM_COMMAND: /* process menu items. */ 


switch (wParam) 


case IDM_| DOIT: /* User hit the "Do it" menu item .*/ 
rye = GetDC (hWnd) ; 
hFont = CreateFont ‘24, 16, 0, 0, 400, 0, 0, 0, 
 OEM_CHARSET, OUT_ DEFAULT “PRECIS, 
* CLIP_ DEFAULT __PRECIS, DEFAULT. QUALITY, 
‘DEFAULT_PITCH | FF SCRIPT, “script"):; 
SelectObject (hdc, hFont) ; 
~ TextOut ChDC, 10, 10, "this is the script font!". 24) ; 
' ReleaseDC (hind, hoe) ; . 
DeleteObject (hFont) 
break ; 
case IDM_QUIT:  /* send end ae application message 4 
Destroydande™ ChWnd) ; . 
break ; 
} . 
break ; : 
case WM DESTROY: y* stop application sea 
Postadi thease (0) ; 
break ; ; 
default: ieee "7* default windows message processing */ 
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return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 
} ‘ 
return (OL) ; 


CREATEF ONTINDIRECT | Win 2.0 Win 3.0 Win 3.1 
Purpose Creates a logical font. 

Syntax HFONT CreateFontIndirect(LOGFONT FAR */pLogFont); 

Description The LOGFONT structure is defined in WINDOWS.H as 

Hdefine LF..FACESIZE 32 


typedef struct tagLOGFONT 
{ 


int lfHeight; 

int LfWidth; | 

int LfEscapement; 

int LfOrientation; 

int LfWeight; 

BYTE lfItalic; 

BYTE LfUnderline; 

BYTE LfStrikeQut; 

BYTE LfCharSet; 

BYTE LfOutPrecision; 

BYTE LfClipPrecision; 

BYTE ° LfQuality; 

BYTE LfPitchAndFamily; . 

BYTE LfFaceNameCLF_FACESIZE]; 

} LOGFONT; 

. typedef LOGFONT *PLOGFONT; - 

typedef LOGFONT NEAR *NPLOGFONT; 

typedef LOGFONT FAR *LPLOGFONT; a 
Each of the elements of the LOGFONT structure has the meaning described in the CreateFont() 

. function description. 

Uses 7 CreateFont() is convenient if one font is being used. For more than one, CreateFontIndirect() is 
more convenient as many of the parameters are repeated for all fonts. 

Returns HFONT, a handle to the font created. This is the handle you use with SelectObject() to make the 
font available for output onto the device context with functions such as TextOut(). Returns NULL 
on error. 

See Also CreateFontindirect(), SelectObject(), TextOutQ), AddFontResource() 

Parameters 

lpLogFont LPLOGFONT: A pointer to a LOGFONT structure. 

Example 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


HDC he ; 
HFONT _ AFont ; 
LOGFONT Af; 
switch (iMessage) /* process windows messages */ 
{ > He, 
case WM_COMMAND: a3 /* process menu items */ 


switch (wParam) 
4 


case-IDM_DOIT: . /* User hit the “Do it" menu item */ 
hDC = GetDC (hWnd) ; : 
Lf.LfHeight = 20; - : = 
Lf .lfWidth = Lf.LfEscapement = Lf.lfOrientation = 0 ; 
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} 


\ 
Lf. lfWeight = FW_NORMAL ; 
Lf.lfitalic =-(f. LfUnderine = Ulf. Lestrikeout 7 0; 
tf.LfCharSet = OEM_CHARSET ; 
Lf. lLfoutPrecision = OUT _DEFAULT_ PRECIS ; 
Lf. LfClipPrecision = CLIP_ DEFAULT. PRECIS ; 
Uf. lfQuality = DEFAULT_QUALITY ; 
Lf .LfPitchAndFamily = DEFAUL: PITCH | FF_DONTCARE ; 
strepy (lf.lfFaceName, nhelv'd 7 
hFont = CreateFontIindirect Calf) ; 
SelectObject C(hDC, hFont) ; 
TextOut ChDC, 10, 10, “This is the font!", 
ReleaseDC (hWnd, hDC) ; 
DeleteObject ChFont) ; 
_ break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; i 
break ; 


17) ; 


} 

break ; 
case WM_ DESTROY: 
PostQuitMessage (0) >; 
SS eae 


/* stop application */ 


default: /* default windows message processing */ 


return en ChWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


} 
CreaTeIC 
’ Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
lpDriverName 


[pDeviceName 
lpOutput 


lpInitData 


eWin2.0 m@8Win3d.0 mWin3l 


Retrieves a device context for a physical Gere, but only for information purposes. Output cannot 
be sent to the device. 


HDC CreateIC(LPSTR lpDriverName, LPSTR lpDeviceName, LPSTR lpOutput, LPSTR. 
lpInitData), 


This function is identical to CreateDC(), except that the device context is not set up for output, 


Frequently used with GetDeviceCaps() to retrieve information about a printer or screen device. 
Also used in setting up memory areas to be compatible a the device context of the screen with 
CreateCompatibleDC(). 


HDC, a device context for the device. Returns NULL on error. 
DeleteDC(), GetProfileString(), GetDeviceCaps(), CreateCompatibleDC() 


LPSTR: A pointer to a null-terminated string containing the DOS file name of the printer driver. 
The driver file is loaded when a new printer is installed under Windows, Example: “PCL/HP 


_, LaserJet.” This is the first parameter on the WIN.INI line that starts with “device=.” 


: 


LPSTR: A pointer to a null-terminated string containing the device name. Example: “HPPCL.” . 


This is the second parameter on the WIN.INI line that starts with “device=.” The parameters are 
separated by commas. Set to NULL for a screen device. . 


LPSTR: A pointer to a null-terminated string containing the output file or device. Example: 
“LPT1:.” This is the third parameter on the WIN.INI line that starts with “device=.” The param 
eters are separated by commas. Set to NULL for a screen device. 


LPDEVMODE: A pointer toa DEVMODE data structure. This structure can be initialized by call- 
ing the ExtDeviceMode() function. Set to NULL to use the default initialization data for the de- 


—_ 


vice specified by the user in the Control Panel application. The DEVMODE structure is defined in - 


DRIVINIT.H as follows: 


/* size of a device name string */ 
#define CCHDEVICENAME 32 
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char dmDeviceNameCCCHDEVICENAME); /* device name string */ 


WORD dmSpecVersion; 
WORD dmDriverVersion; 
WORD dmSize; 

WORD dmDriverExtra; 
OWORD dmFields; 


short dmOrientation; 
short dmPaperSize; 


/* driver specification ver. eg. 0x300 */ 
/* OEM dirver version number */ 

/* size of DEVMODE structure */ 

/* number of bytes following DEVMODE data */ 
/* bitfield for which of the following dm */ 
/* values are supported. Bit 0 is one if */ 
/* dmOrientation is supported, etc. */ 


' /* DMORIENT_PORTRAIT or DMORIENT_LANDSCAPE */ 


/* DMPAPER_LETTER, DM_PAPER_LEGAL, DM_PAPER_A4 */ 


/*® DMPAPER_CSCHEET, DMPAPER_DSCHEET, DMPAPER_ESHEET, DMPAPER_ENV_9 */ 
/* OMPAPER_ENV_ 10, DMPAPER_ENV_11, DMPAPER_ENV_12, DMPAPER_ENV_14 */ 


short dmPaperLength; 
short dmPaperWidth; 
short dmScale; 

short dmCopies; 

short dmDefaultSource; 
short dmPrintQuality; 


short dmColor; 
short dmDuplex; 


/* overrides dmPaperSize, in mm/10 */ 

/* overrides dmPaperSize, in mm/10 */ 

/* page is scaled by dmScate/100 */ 

/* number of copies supported */ 

/* Default paper bin */ 

/* DMRES_HIGH, DMRES_MEDIUM, DMRES_LOW, */ 
/* or DMRES_DRAFT */ 

/* DMCOLOR_COLOR or DMCOLOR_MONOCHROME */ 
/* DMDUP_SIMPLEX, DMDUP_HORIZONTAL, */ 

/* or DMDUP VERTICAL */ 


BYTE dmDriverData CdmDriverExtralj ; /* Oor more bytes of extra data */ 


} DEVMODE; 


typedef DEVMODE * PDEVMODE, NEAR * NPDEVMODE, FAR * LPDEVMODE; 


Example This is a fragment of a WndProc() function that uses CreatelC() to get an information context for 
the screen. Using the context, the program finds the number of bits per pixel and the number of 
color planes for the display. For a VGA screen, this will show | bit and 4 color planes. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ , 


HDC 
char 
int 


switch (iMessage) 
{ 


case WM_COMMAND: 
switch (wParam) 


{ 


hoc 3 
cBuf £10] ; 
nBits, nColorPlanes ;° 
/* process windows messages */ 


/* process menu items */ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 


[Other program lines] 
DELETEDC 


hDC = CreateIC ("DISPLAY", NULL, NULL, NUL? ; 
nBits = GetDeviceCaps ChDC, BITSPIXEL) ; 
nColorPlanes = ee tvev ise Gaps ChoDCc, PLANES) ; 
DeleteDC C(hDC) ; 

hOC = GetDC Chiind) ; 

TextOut (hDC, 10, 10, "Cotor per pixel =", 17) ; 
itoa (nBits, cBuf, 10) ; 

TextOut (hDC, 10, 30, cBuf, strlen (cBuf)) ; 
TextOut (hdC, 10, 50, “Color planes =", 14) ; 
jitoa (nColorPlanes, cBuf, 10) ; 

TextOut (hDC, 10, 70, cBuf, strlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 

break ; 


mw Win2.0 mWin3.0 mWin3.1 


Purpose Deletes a device context created with CreateDC(), CreateCompatibleDC(), or CreateIC(). 
Syntax BOOL DeleteDC(HDC ADC); 


Description Device contexts take up memory in the system. Use this function to free the device context ; as 
soon as possible after use. 
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Uses Used any time CreateDCQ), CreateCompatibleDC(), or CreateIC() was used to create a device 

context. Do not use it if GetDCQ w was used to create a device context for a window. In that case, 
. use ReleaseDC(). 

Returns BOOL. TRUE if the device context was dcléted. FALSE on error. 

See Also CreateDCO, CreatelC0, CreateCompatibleDC() 

Parameters | 

hDC HDC: A handle iG the device context created with CreateDC(), CreateCompatibleDC(), or 
CreatelC(). 

Example The previous example, shown under CreateIC(Q), shows the device context being deleted after 
use. Note how GetDC() is used afterwards to obtain a separate device context for ou to the 
window’s client area. 

DEVICECAPABILITIES | OWin2.0° eWin30 gWin3l 

Purpose Determines the capabilities of a device, such as a printer. . 

Syntax DWORD DeviceCapabilities (LPSTR IpDeviceName, LPSTR lpPort, WORD nade, LPSTR 
lpOutput, LEDEVMODE lpDevMode); 

Include File. <drivinit.h> 

Description Physical devices, such. as printers, are accessed by calling functions within a device driver file. 


The file, with the extension .DRV, will reside in the Windows system directory. Drivers are spe- 
cialized DLLs (dynamic link libraries). Functions within these DLLs can be accessed to deter- — 
mine the capabilities of the physical device. See Chapter 28 for more details on DLLs. 
DeviceCapabilities() is a function that is expected to.be supported within the driver file. The 
function is called indirectly by first loading the driver file with LoadLibrary(), and then obtaining 
the DeviceCapabilities() function address within the driver with GetProcAddress(). The 
DRIVINIT.H header file includes the following two typedef statements for use with 
GetProcAddress() to reference the DeviceCapabilities() function within the driver file. 


typedef DWORD FAR PASCAL FNDEVCAPS(LPSTR, RSTn? WORD, LPSTR, LPDEVMODE) ; 
typedef FNDEVCAPS FAR * LPFNDEVCAPS; 


Uses 
Returns 
See Also 


Parameters 
lpDeviceName 


lpPort 


nindex | 


Determining the paper sizes, paper bins, etc. that a printer supports. 
DWORD. The returned value depends on the nJndex value specified. Returns 1 on error. 


CreateDC(), ExtDeviceMode(), LoadLibrary(), GetProonddress(); GetProtileString(), 
GetSystemDirectory() 


LPSTR: A pointer to a null-terminated character string containing the printer device name, such 
as “PCL/HP LaserJet.” Use GetProfileString() to obtain this string from the WJN.INI file. 
LPSTR: A pointer to a null-terminated character string containing the name of the port to which 
the device is connected, such as “LPT1:.” This string can also be obtained from WIN.INI. 


WORD: Specifies which value to obtain from the device. It can be any of the indices listed in 
Table 10-4 and defined in DRIVINIT.H. 


ea. Meaning 


DC. BINNAMES 


If the printer ae does not stsuneod multiple bins, DeviceCapabilities( ) returns 0. If uipe bins 
are supported, DeviceCapabilities( ) returns the number of bins. /oOutput should then point to a 
memory buffer to hold data on the bins. The data consists of an array of integers, each 
containing the bin ID number ene for each bin). This is followed by the-bin names, each 24 
characters long. 


368 


10. DEVICE CONTEXTS, TEXT OUTPUT, AND PRINTING ¥ 


Set /oOutput to NULL to simply retum the number of bins supported. This is usually done 
to determine the number of bytes to allocate for the bin numbers and names (26 bytes per bin, 
DC_BINS If fpOutput is set to NULL, DeviceCapabilities( ) retums the number of paper bins the printer 


supports. If /pOuput is not NULL, it should contain a pointer to a memory buffer. The buffer will 
receive an array of WORD values, each containing a bin number. 


DC_COPIES (Win 3.1) DeviceCapabilities( ) returns the maximum number of copies that the printer can produce. 
“~_DC_DRIVER -  DeviceCapabilities( ) retums the printer driver version number. . 

DC_DUPLEX Retums 1 if the printer supports duplex printing, 0 if not. 

DC_ENUMRESOLUTIONS if JpOutput is set to NULL, DeviceCapabilities() retums the number output resolutions the printer 

(Win 3.1) supports. If jpOuput is not NULL, it should contain a pointer to a memory buffer. The buffer will 


receive an array of groups of two LONG integer values, each containing the horizontal and 
vertical resolution supported. | 


DC_EXTRA Returns the number of bytes of device specific data at the end of the DEVMODE structure for 


the printer driver, 
DC_FIELDS a Returns the bit-field value which specifies which features are supported by the ea driver. 


This is the same as the dmFields element of the DEVMODE structure. 


DC_FILEDEPENDENCIES If JoOutput is set to NULL, DeviceCapabilities( ) returns the number of files which need to be 

(Win 3.1) » loaded to make the printer work. If /oOuput is not NULL, it should contain a pointer to a memory 
buffer. The buffer will receive an array of 64 character long file names, each containing the file 
name of a file that must be loaded to support the printer. 


DC_MAXEXTENT Returns a POINT structure containing the maximum paper size that the printer can support. 
These are the largest values that can be placed in the dmPaperLength and dmPaperWidth 
elements of the DEVMODE structure. 


DC_MINEXTENT Returns a POINT structure containing the minimum paper size that the printer can support. 
These are the smallest values that can be placed in the cimPaperLenath and dmPaperWidth 
elements of the DEVMODE structure. 


DC_PAPERS If pOutput is set to NULL, DeviceCapabilities( ) retums the number of supported paper sizes, 
This is the normal use of this fiag. If Ouput is not NULL, it should contain a pointer to a 
memory buffer. The buffer will receive an array of WORD values, each containing a supported 
paper size. 


DC_PAPERSIZE [pOutput should contain a pointer to a memory buffer. The buffer will receive an array of POINT . 
values, each containing the horizontal and vertical size in 1/10 mm for supported paper sizes. 
Use DC_PAPERS first to determine the size of the data buffer needed to contain the POINT 


data. 
DC_SIZE DeviceCapabilities( ) returns the size of the DEVMODE data structure, not Spates any driver- 
es specific data following the structure. This i is the same as the dmSize element of the DEVMODE 
oe data structure. 
_DC_VERSION DeviceCapabilities( ) retums the Microsoft driver specification number to which the driver 
conforms. 
Table 10-4. DeviceCapabilities() Index Values. ~ 
IpOutput LPSTR: A pointer to a memory buffer. The data received i in the buffer will depend on the nIndex 
OS ~ value, as described above. 
lpDevMatte .  LPDEVMODE: Normally, set to NULL. In this case, DeviceCapabilities() returns the current 


initialization values for the specified driver. If lpDevMode is not NULL, it should contain a 
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-. pointer to a DEVMODE data structure containing the values to be read by DeviceCapabilities(). 


west ctnsiy!"-, »- DEVMODE is defined in DRIVINITH as follows: 


/* sizeof atdevice: name. string we 
H#define CCHDEVICENAME 32.; 


typedef struct _devicemode ben 


char. dmDeviceNamel CCHDEVICENAME]; . oy t+, 4* device name string */ 


WORD dmSpecVersion; {* driver specification ver. eg. 0x300 */ 
WORD dmDriverVersion; 0.) 20° 03 /* OEM dirver version number */ 

WORD dmSize;' ° So tes _ _/* size of DEVMODE structure */ 

WORD dmOriverExtra; gtr kane e ‘/* number of bytes following DEVMODE data */ 
,DWORD dmFields;. . Siete: ashe ott 7 /* bit-field for which of the following dm */_ 


/*evalues are supported. 


Bit 0 is one if */ 


He eat ae ee Pe te PEE Ry. /* dmOrientation is supported, etc. */ 
short. dmOrientation; .. 04 | _. SE DMORIENT PORTRAIT or DMORIENT_LANDSCAPE */ 
short dmPaperSize; , /* DMPAPER_LETTER, DM_PAPER_LEGAL, DM_PAPER_A4 */ 
/* DMPAPER_CSCHEET, DMPAPER_DSCHEET, ODMPAPER_ESHEET, DMPAPER_ENV_9 */ 
Dy A DMPAPER_ ENV —10,. DMPAPER_ENV_11, DMPAPER_ENV_ 42, DMPAPER_ENV_14 */ 


short ‘dmPaperLength; ; /* overrides dmPaperSize, in mm/10 */ 
short dmPaperWidth; /* overrides dmPaperSize, in mm/10 */ 
short dmScale;, .._., saat es /* page is scaled by dmScale/100 */ 
short dmCopies; aaa... ¢* number of copies supported */ 
short dmDefaultSource;” «=. - oefe 0 3. -J* Default paper bin */ 
short. dmPrintQualitys.............. /* DMRES_HIGH, DMRES_MEDIUM, DMRES_LOW, */. 
eR See Pete me a /* or DMRES_DRAFT */ | 
‘short dmColor; oo. aon /* DMCOLOR COLOR or DMCOLOR_MONOCHROME */ 
short _dmDuplex; . rete, 7 : 1 /*.DMDUP_SIMPLEX, DMDUP_HORIZONTAL, */ 
a ~-* or DMDUP_VERTICAL */ 
BYTE dmDriverData CdmDriverExtrad ; “/* 0 or more bytes of extra data */ 
} DEVMODE; 


typedet! DEVMODE* PDEVMODE, NEAR'*. NPDEVMODE, FAR * LPDEVMODE; 


Example This example, which is illustrated i in Figure 10-4, displays the 

“os <<“ printer driver name, OEM driver number, and the paper sizes 

ou)". “gupyported'when the user clicks the “Do It! menu item. The 

driver name is determined by parsing the WIN.INI file entry 

sve. uc: “device=.” The driver file is in the Windows system directory. 

sei t,°° The directory name is determined by calling GetSystemDirectory(). 

cae. ‘When the full directory/file name string for the dirver file has 

been assembled, the driver is loaded with LoadLibrary(). 

., +. «,,, GetProcAddress() is used to obtain the address of the De- 

sce viceCapabilities() function within the driver file. This is ex- 

pion ecuted twice to determine the driver number and-supported 
paper sizes. 


Dolt! Quit 
‘Driver = HPPCL 


Figure 10-4. Device- 


Capabilities.) Example. 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ Ae zi ety as i : = ee a i . * - = 
Soe ghar) "°° 2" szprinter [64], szSysDir C128], szFullDriver C256], 
: *szDriver, *szDevice, *szOutput, cBuf [128] ; 
HANDLE hDriver ; | : ; 
~ LPFNDEVCAPS © ““-lpDeviceCaps ; 
DWORD © dwVersion, dulumr spersize ; 
POINT oP nt aT ray C20] ; 
“HDC UO hdc ; 
int ; i; —_ 
switch wines ese a proces indous mesenger xf 
Dah Me lens aa eae 
case WM, _ COMMAND: : [+ process menu items ne 
ambeay cebarem) : 


t 


her Oh LV feed 
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‘GetProfiteString (“windows", “device”, "", szPrinter, 64) ; 
szDevice.= strtok (szPrinter, me) s 
7 szDriver = strtok (NULL, ",") ; 
szOutput = strtok (NULL, " muy 
. 4* build full driver path/file s spec */ 
GetSystemDirectory (szSysDir, 128) ; 
istrcepy (szFullDriver, szSysDir) ; 
istrcat (szFullOriver, "\\").; |. 
lstreat (szFullbriver,’ szDriver) 2 
_lstreat (szFullDOriver, ".DRV") > _ 
/* get handle to driver ‘ey 
hDriver = LoadLibrary (szFullDriver) ; 
if ChDriver > 31) 
{ /* get address of DeviceCaps func. */ 
' LpDeviceCaps = 
CLPFNDEVCAPS) GetProcAddress (hdriver, 
“DeviceCapabilities") ; 
df ClpDeviceCaps) /* use peviceCaps func. *] 


dwVersion = (* LpDeviceCaps) (szPrinter, 
szOutput, DC_DRIVER, NULL, . NULL) ; 
dwNumPapersize = 
(* LpDeviceCaps) (szPrinter, 
szOutput, DC_PAPERSIZE, 
(LPSTR) PointArray, NULL) ; 
' /* output results */ 
hDC = GetDC (hWnd) ; 
TextOut (hDC, 0, 0, cBuf, wsprintf (cBuf, 
"Driver = %s", (LPSTR) szDriver)) ; 
TextOut Choc, 0, 20, cBuf, wsprintf (cBuf, 
“Driver No. xd, Paper sizes:", 
phan a ae 
for Ci=O;i< dwNumPapersize 3 itt) 
_ TextOut Choc, 0, 40 + (i * 20), cBuf, 
wsprintf (cBuf, "%d) Xdmm X Z2dmm", 
; i+1, PointArrayCil.x 7 10, 
PointArraylid. y /10)) ; 
aaleeiene ChWnd, hDC) ; 


i : 
} “ss 
“else 
MessageBox ChWnd,- fouled not Load driver file.", 
"Message", MB_OK) ; 
. break 3 
[Other program itnes} 
DPToLP - ype ee Win 2.0m Win3.0) mi Win 3.1 
Purpose Converts from device points to logical points. 
| Syntax BOOL DPtoLP(HDC DC, LPPOINT IpPoints, int nCount); 
Description When a window’s client area device context is first captured, the MM_TEXT mapping mode is set. 


- This means that the measurement units for locations in the client area are in pixels, measured 
from the top left corner. As soon as a different mapping mode is set, or the origin is moved, the 
measurements of a point’s location switch to logical units. DPtoLP() allows you to convert one or 

~ more points from device coordinates to logical coordinates. 


Uses . Used after the mapping mode or origin has been changed, usually to plot items relative to the 
Sr re ’ boundary of the window. 

Returns — , BOOL. TRUE if the points were converted, FALSE onerror, — 

. ‘See Also . SetViewportOre0, Son nome TRO Setilaptioded) LPtoDPQ . 

Parameters ae i . e —_ 


hDC - | HDC: The device context. ost. 
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lpPoints LPPOINT: A oe to an array of .one-or-more ert struc- 
tures. 

nCount int: The number of POINT i in the i IpPoints array.’ 

Related Messages WM_SIZE | 

Example This example, as shown i in 1 Figure 10- 5, draws an X Gia corner 


to corner of the client area after. the mapping mode has been 
changed. This requires converting the coordinates of the cor- 
ners of the client area into logical coordinates before the lines Figure 10-5. DPtoLP() 
are drawn. . 7 Example. 


Long FAR PASCAL WndProc CHWND hwnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


aa. 


HOC: PEN hoc ; 

static 2 POINT ptClientSize, ptCenter ; 

POINT ptCorners [4] ; 
switch (iMessage) : /* process windows messages */ 
{ 


case WM SIZE: “/* get client area size */ 
ptClientSize.x = LOWORD (lParam) ; 
ptClientSize. y = HIWORD (lParam) ; 


a _ break ; 
case WM_COMMAND:. .. m /* process menu items */ 
switch (wParam). : 
; f 
case IDM_| DOIT: ; /* User hit the "Do it" menu item */ 


- ADC = GetDC ChwWnd) ; 

. SetMapMode (hOC, MM_LOMETRIC) ; 
ptCenter.x = ptClientSize.x / 2 ;/* calc center in */ 

. ptCenter.y = ptClientSize.y / 2 ;/* device units */ 

SetViewportOrg pigs ptCenter. x, ptCenter.y) ; 
ptCorners COJ.x = 0; /* window corners in */ 
ptCorners COJ.y =0; /* device units */ 
ptCorners C1].x = ptClientSize.x ; 
ptCorners C1J.y : 


4 
ptCorners C2].x = ptClientSize.x ; 


th wwe lps " 


- ptCorners C2j.y = ptClientSize.y ; 
ptCorners C3].x = 0; 
ptCorners (3].y = ptClientSize.y ; 


/* now convert ‘to logical coordinates */ 
DPtoLP (hDC, CLPPOINT) &ptCorners, 4) ; 
MoveTo (hDC, ptCorners [OJ.x, ptCorners COJ.y) 
LineTo (hDC, ptCorners [2].x, ptCorners [2].y) 
MoveTo (hDC, ptCorners (11.x, ptCorners Ci].y) 
LineTo (hDC, ptCorners (31.x, ptCorners [3].y) 
ReleaseDC (hWnd, hDC) ; : 


‘Ma Ns 


Nae Ne 


break ; 

[Other program lines] # 

‘DRAWITEXT __ sees, a Pe end, he USS wWin20 mWin3.0 mWin3.l 

Purpose ~ Formats a text string to fit within the bounds of a rectangle. 

Syntax int DrawText(HDCADG, LPSTR lpString, int nCount, LPRECT 

:* . lpRect, WORD wFormat); 

Description DrawText() uses the currently selected text font, color, and This is a long string of text 
background to draw the text. Lines are wrapped to fit within without any CRJLF pairs to 
the bounds of the rectangle. break the line. DrawText] is 

used to format the line. 

Uses . Used in place of TextOut() when the output string may be too 


. long to fit in one line. Unless the DT_NOCLIP format is used,the Figure 10-6. nee ) 
text will be clipped if the line(s) cannot be fit into the rectangle. Example. 
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Returns 
See Also 
Parameters 
hDC 
lpString 


nCount 


lpRect 


wFormat 
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int, the height of the output text in device units. 
TextOut() 


HDC: The handle to the device context. Use GetDC() to retrieve a device context for the window, 
or BeginPaint() if processing a WM_PAINT message. 


LPSTR: A pointer to a string. If the string is null-terminated, the nCount vatrawietet can be set to 
—l. Otherwise, the string length will need to be specified. 


int: The number of characters to output. Set to -1 if the string is null-terminated and you wish to 
output the entire string. 


LPRECT: A pointer to the rectangle that will contain the text. Logical coordinates are used. Use 
GetClientRect() to obtain the client area rectangle. Use DPtoLP() to convert from device units to 
logical units if the mapping mode has been changed. 


WORD: One of the values listed in Table 10-5. These values can be combined with the C language 
binary OR operator oo 


t- 


DT_CALCRECT 


DT_CENTER 
DT_EXPANDTABS 


Calculates the size of the Seca necessary to hold the text. If the DT_SINGLELINE style is 
used, the width is adjusted to fit the text. Otherwise, the width is species! in the loRect 
parameter and the bottom is extended to fit the text. 


Centers the text horizontally. | 
Expands tab characters. The default tab stops are set at eight character widths. See 


DT_TABSTOP. 

DT_EXTERNALLEADING Includes the font’s externa! leading size in computing line spacing. Normally, the external leading 
dimension is not added to the character height in computing line spacing. 

DT_LEFT ‘Left justification. * 

DT_NOCLIP Draws the text without clipping. This is faster, but does not assure that the text wil be within the 
bounds of the rectangle. 

DT_NOPREFIX Normally, “&" characters are used to underline the following letter, and “&&’ is used to print a 
single “&.” By specifying DT_NOPREFIX, et characters have no pee meaning and are 
printed as is. 

DT_RIGHT - Right justification. 

DT_SINGLELINE Specifies a single line of text. 

DT_TABSTOP Sets the tab stops. The high-order byte of wFormat should be used to set the number of 
characters per tab stop. 

DT_TOP Top justification. Must be used with DT _SINGLELINE. 

DT_VCENTER Vertically centered justification. Must be used with DT_ SINGLELINE, - 

DT_WORDBREAK Specifies that spaces between words will be used to break lines that would otherwise exceed 


the size of the rectangle. CR/LF pairs also break the line. 


Table 10-5. DrawText() Flags. 


Example 


‘This is a WndProc() program fragment showing Drawtext() being used to format a sone line of 
text. The result is as shown i in Figure 10-6. 


Long FAR PASCAL ¥adFnos CHWND hwnd, unsigned inessage, WORD Geatoa, LONG tParau) 
{ 


HDC 


hoc ; 


“373 


WINDOWS APIBIBLE .. 


RECT rTextRect ; 
static char cBuf CJ] = “this dsia Long string of text without any CR/LF \\ 
pairs to break the line. DrawText() is used to \\. | :: 
format the line." ; 7 ne 
suitch (iMessage) . , Sarr ee ree ae process windows messages */ 
case WM_COMMAND: =~ .:- = /* process menu items */ - 
suite cur aren. ee re ae e ee 
case IDM.DOIT: «-:; -.:.:'/* User hit the "Do it” menu item */ 
SetRect. (arTextRect, 10, 10, 200, 400) ; 
“ADC = GetDC (hWnd) ; 
DrawText ChDC, cBut, -1, ErTextRect, 
DT_LEFT | DT_! WORDBREAK) ; 
ReleaseDC: ¢€hWnd, nDon? 
Be eS be Gihbnnngits adn ORE break 2 ee 
[Other program lines] 
EnumF onts | , mWin20,. mWin30 mWin3.t 
Purpose _ Finds (enumerates) all of the fonts available on‘a given device. All of the data in the LOGEONT 
; z and TEXTMETRIC structure types is available for examination on each font enumerated. © 
Syntax , int EnumFonts(HDC hDC, LPSTR lpFacename, FARPROC lpFontFunc, LPSTR lpData); 
Description — EnumFonts() works by using a callback function. You define the callback function in your pro- 
gram, and pass it to the enumeration function as a procedure-instance address [pFontFunc. The 
enumeration function is called once for every font found. This gives the enumeration function a 
ae chance to examine and store data from each. font as desired. Both the LOGFONT and 
TEXTMETRIC data associated with a font is available on each pass of the enumeration function. 
Uses Ideal for filling a list box with the fonts available on the system when the program is started. 
Returns The last returned. value by the callback function. This is determined by how you program me 
callback function. Normally, the returned value is not used. 
See Also AddFontResource(), CreateFont(), CreateFontindirect(), GetDC( ) 
Parameters 
hDC . HDC: The device context of the device that contains the fonts, 
lpFacename. LPSTR: A long pointer toa typeface name. Set to NULL to enumerate each type of font: Set 
lpFacename pointing to a character buffer cones a typeface name to enumerate each size or 
type for a given typeface. - ; 
lpFontFunc FARPROC: The procedure-instance address of ‘the enumeration function. “Use 
MakeProcInstance() to create this value. The function 1 name must also be listed in the EXPORTS 
section of the .DEF definition file. 
lpData -LPSTR: A 32-bit value passed to the enumeration function. This is usually a memory handle to . 


the beginning of a memory buffer that will hold the data captured by the enumeration function. 
The enumeration. finesion should metuates the memory huffer each time it needs to aces a new 
item. 


Enumeration (Callback) Function 


int FAR PASCAL FontFune (LPLOGFONT ipiioo Font, LPTEXTMETRICS lpTeatMetrics, shor. 
nFontType, LPSTR lpData) — 

The enumeration function will be called once for each font found. The enumeration functior 
should return a nonzero value to continue enumeration, zero to stop enumeration. Zero is typi- 
cally reuuraed« on error, such as not ot being able to allocate 1 more Memory. , 


374. 


Parameters 
lpLogFont 


lpTextMetrics 


nFontType 


Example 


/* generic.h 


Hdefine IDM_DOIT 1 
Hdefine IDM_QUIT. 2 
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LPLOGFONT: A pointer to a logical font structure. The ele- 

_ ments of the structure will be set to a different font’s values on . 
each call to the enumeration function. See.the CreateFont- .. 
Indirect() function description for a listing of this structure. ceas 


LPTEXTMETRICS: A pointer to a TEXTMETRIC structure. The 


elements of the structure will be set to a different font’s values 


‘on each call to the enumeration function. See the GetText- 
Metrics() function description for a listing of this structure. . 


short: Specifies the type of font found. This is a combination of 
RASTER_FONTTYPE or DEVICE_FONTTYPE. If nFontType 
| RASTER_FONTTYPE is TRUE, then the font is a raster font. 
Otherwise, it is a vector font. If nFontType | DEVICE_FONT- 

_TYPE is TRUE the font is a device font. oe it is a GDI 
font. 


This example, illustrated in Figure 10-7, lists the names of every 
font type available to the system. In this case, only the font 
name is extracted from the logical font structure. 


‘| EnumFont§ found: 


Ff senator isla" 


System... 
Terminal 
Helv 
Courier 
Tms Rmn 
Symbol 
Roman 
Script 
, Modern 
\ Preview 


Figure 10-7. EnumFonts() 
Example. 


. The program’s header file includes the structure definition for the ENUMER type. This is a 
handy structure to use in enumeration functions, as it keeps the number of items found and the 
memory handle together in one structure. The enumeration function prototype is at the end of 


the header file. 
*/ 


/* menu item id values */ 


/* definitions */ 


H#define TITLEWIDE 


typedef struct 
{ 


20 


GLOBALHANDLE hGMem ; 
int nCount ; 
} ENUMER ; 


/* global variables */ 


int 
char 


ghInstance ; 
gszAppName EJ = 


eae 
"generic" ; 


/* function prototypes */ 
Long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 
BOOL FAR PASCAL FontEnumFune SEEPECSrOnt lf, LPTEXTMETRIC tm, short nFontlypes 
ENUMER FAR *enumer) ; 


The enumeration function name must also be listed in the EXPORT® ‘ection of the program's 
.DEF definition file. The WndProc() function of the program is shown ii. the following program. 
The enumeration function is called when the user hits the “Do It!” menu item. The font names are 
then shown on the screen. Note that the font names end ays one- tee nes in the ENUMER 


data structure’s data pointed to by GMem. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) ° SB 
{ : Epoveehg, EGG SB ae 


static FARPROC. LpfnEnumProc ; — - 


static ENUMER 


LPSTR 
HDC 
int 


-enumer -; 
LpFontName ; 
hDC ; 

i; 
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switch (iMessage) /* process windows messages */ 
{ : 
; case WM_CREATE: . 

UpfnEnumProc = MakeProcInstance (FontEnumFunc, ghInstance) ; 


break ; 
“case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ z 
case IDM_ DOIT: /* User hit the “Do it" menu item */ 


if Cenumer.hGMem) /* if not first time tried */ 

GlobalFree Cenumer.hGMem) ;/* free the memory */ 
enumer.hGMem = GlobalALlloc (GMEM_MOVEABLE 

_ GMEM_ZEROINIT, 1L) ; 
enumer.nCount = 0 ; 
hDC = GetDC (hWnd) ; 
/* Let Windows run callback func. */ 

EnumFonts ChDC, NULL, LpfnEnumProc, 

CLPSTR) &enumer) ; 
ipFontName = GlobalLock Cenumer.hGMem) ; /* Lock mem */ 
TextOut (hDC, 10, 0, “EnumFont() found:", 17) ; 
for (i = 0; i < enumer.nCount ; i++)/* disp font names */ 
{ 

TextOut ChDC, 15, 20 + (15 * i), 

'  (LPSTR) ClpFontName + Ci * LF_FACESIZE)), 
Lstrlen (ipFontName + Ci * LF_FACESIZE))) ; 
} 
GlobalUnlock Cenumer.hGMem) ; /* unlock memory */ 
: petessenG ChWnd, hDC) ; 
_ break ; 
case IDM_QUIT: 

Destroy" inden (hwnd); 


break ; 
} 
break ; 
case WM__ DESTROY: : oe stop application */ 
GlobalFree Cenumer. hGMem) ; /* release all memory */ 


FreeProcInstance CiRThEnuneie) ; 
PostQuitMessage (0) ; 


break ; 
default: _ /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam; lParam) ; 
} 7 


return (QOL) ; 


int FAR PASCAL FontEnumFunc (LPLOGFONT Lf, LPTEXTMETRIC tm, short aponeiieds 
ENUMER FAR *enumer) 


{ 
LPSTR ipFontFace ; 
if (!GlobalReAlloc Cenumer->hGMem, 
CDWORD) LF_FACESIZE * Cenumer->nCount + 1), 
GMEM_MOVEABLE) ) /* make room for 1 more */ 
return (0) ; /* quit if can't make room */ 
lpFontFace = GlobalLock (enumer->hGMem) ; /* Lock the memory area */ 
‘ys put next name at end */ 
lstrcpy (lpFontFace + (Cenumer->nCount) * LF_FACESIZE), 
CLPSTR) tf->lfFaceName) ; 
GlobalUntock Cenumer->hGMem) |; /* unlock the memory area */ 
enumer~>nCount++ ; /* keep track of how many */ 
return (1) ; 
} \ 
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ExtTDEvicEMopDE OWin2.0. mWin3.0 mWin3.1 
Purpose Determines or modifies the initialization data for a printer driver. Displays a dialog box for modi- 
fying the driver settings. 
Include File <drivinit.h> 
Syntax int ExtDevice’fode (HWND hWnd, HANDLE hDriver, LEDEVMODE [pDevModeOutput, LPSTR 
lpDeviceName, LPSTR lpPort, LEDEVMODE l[pDevModelnput, LPSTR lpProfile, WORD wMode), 
Description Physical devices, such as printers, are accessed by calling functions within a device driver file. 


The file, with the extension .DRV, will reside in the Windows system directory. Drivers are spe- 
cialized DLL (dynamic link library) files. Functions within these DLLs can be accessed to deter- 
mine the capabilities of the physical device. See Chapter 28 for more details on DLLs. 

ExtDeviceMode() is a function that is expected to be supported within the driver file. The 
function is called indirectly by first loading the driver file with LoadLibrary(), and then obtaining 
the DeviceCapabilities() function address within the driver with GetProcAddress(). The driver 
file contains the dialog box definition for modifying the driver settings. The DRIVINIT.H header 
file includes the following two typedef statements for use with seticedaresO | to reference 
the DeviceCapabilities() function within the driver file. 


typedef WORD FAR PASCAL FNDEVMODECHWND, HANDLE, LPDEVMODE, LPSTR, 


LPSTR, LPDEVMODE, LPSTR, WORD); 


typedef FNDEVMODE FAR * LPFNDEVMODE; 


Uses 


Returns 


See Also 


Parameters 
hWnd 


hDriver 


lpDevModeOutput 
lpDeviceName 
lpPort 


lpDevModelnput 


Used to display the printer dialog box so that the user can modify the printer settings. Also used 
to fill a DEVMODE structure for use by the CreateDC() and DeviceCapabilities() functions. 

int. Returns the size of the DEVMODE data structure for the printer driver if wMode is NULL. 
Returns IDOK or IDCANCEL if a dialog box was presented to the user. Returns a negative value if 
an error occurred. 


een pence ewenincet GorbroMlesuiney); LoadLibrary(), GetProcAddress() 


HWND: A window handle. If a printer setup dialog box is displayed, hWnd will be the parent 
window. 

HANDLE: The handle of the device-driver module. This value is obtained by calling LoadLibrary() 
or GetModuleHandle(). . 

LPDEVMODE: A pointer to a DEVMODE data structure. The data structure will be filled when 
ExtDeviceMode() returns. If initialization data is supplied in lp DevModeInput, this will be cop- - 
ied to the structure pointed to by /pDevModeOutput before any changes are made. 

LPSTR: A pointer to a null-terminated character string containing the name of the printer device 
such as “PCL/HP LaserJet.” This value can be obtained by reading the WIN.INI file using 
GetProfileString(). See the following example. 

LPSTR: A pointer to a null-terminated character string containing the name of the port to which 
the printer is attached. This value can also be obtained by ene the WIN.INI file using 
GetProfileString(). i 
LPDEVMODE: A pointer to a DEVMODE data structure that contains initialization data for the 
printer device. The data will be copied to the buffer pointed to by lpDevModeOutput before any 


_ modification occurs. Set to NULL to use the default initialization data based on the Windows 
_ Control Panel application. 


- wMode 


WORD: Specifies the action ExtDeviceMode() should take. It should be one or more of the follow- 
ing values, combined with the C language binary OR operator (1). 
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- > Meaning: | 


Zero (0) 
DM.COPY 
DM_MODIFY 
DM_PROMPT 


DM_UPDATE . 


EiDevioeMode ) returns the size of the memory buffer in bytes needed to hold the DEVMODE data for the 


printer. This includes the printer-specific data at the end of the DEVMODE structure. IpDevModeOutput 
can be set to NUIL for this use of ExtDeviceMode( ). 


~ Writes the current printer initialization data to the DEVMODE data structure pointed to by 


IpDevModeOutput. This is done in advance of calling CreateDC(). 


- The data i in the (pDevModelnput DEVMODE structure is copied to pDevModeOutput beave any modifi ica- 
tions to the setup data begin. This is useful if application-specific printer setups are stored, preferably in a 
- private initialization fi le. if this flag is not used, pDevModeOutput. can be set to NULL. 


ss Presents the printer driver Printer Setup dialog box, and allows the user to change values. The dialog box is is 
_ defined in the driver file. 


The printer driver settings are copied to the WIN. INI fi le when ExtDeviceMode() exits, 


fable 10: 6 ExtDeviceMode( ) Flags. 


The DEVMODE date structure is defined i in 1 DRIVINIT. H as follows: 


"“/* size of a device name string */ 
#define CCHDEVICENAME 32 


typedef struct 


_devicemode { 


char dmDeviceNamel CCHDEVICENAME]; /* device name string */ 
WORD dmSpecVersion; : i . ./* driver specification ver. eg. 0x300 */ 
WORD. dmDriverVersion; y her “g /* OEM-dirver version number */ 
WORD dmSize; ves A size of DEVMODE structure */ — : 
_ WORD dmDriverExtra; __. ¢* number of bytes following DEVMODE data */ 
 DWORD dmFields; pens ; '. /* bit-field for which of the following dm */ 


/* values are supported. Bit 0 is-one if */ 
/* dmOrientation is supported, etc. */ 


short dmOrientation;; °°. /* DMORIENT_PORTRALT or DMORIENT_LANDSCAPE */ 
short dmPaperSize; /* DMPAPER_LETTER, DM_PAPER_LEGAL, DM_PAPER_A4. */ 


/* DMPAPER_CSCHEET, DMPAPER_DSCHEET, DMPAPER_ESHEET, DMPAPER_ENV_9 */ 
/* DMPAPER-ENV_10, DMPAPER_ENV_11, DMPAPER_ ENV.12, DMPAPER__ ENV_14 */ 


share dmPaperLength; . /* overcides dmPaperSize, in mm/10 */ 


short dmPaperWidth; ” * overrides dmPaperSize, in mm/10.*/ 
-“short dmScale; = 0) 0 Vu wt. . J * page ‘is scaled by dmScale/100 */ © 
short dmCopies; /* number of copies supported. */ 
- short dmDefaultSource; - /* Default paper bin */ 
’ short:dmPrintQuality; Le : ; : /* DMRES_| HIGH, DMRES MEDIUM, ‘DMRES_ tow, * 
Re ae tee ae -...., 7* or DMRES_DRAFT. */ 
“= short dmColor;) - /* DMCOLOR_COLOR or DMCOLOR_| MONOCHROME */ 
short dmDuplex;. 2) °: we Paks ' 7* DMDUP_SIMPLEX, DMDUP_HORIZONTAL, */ 
/* or DMDUP_VERTICAL */ 
BYTE ‘dnbriverData Cdmbriverextrad ; oh 0 or more bytes. of extra data: +) 
+ DEVMODE;””. ; 
typedef DEVMODE * PDEVMODE, NEAR * NPDEVMODE, FAR * LPDEVMODE; | auEeuaeeeeererrreecsc 
' 7 . - r ; Z . B . Briater . : Reais a ee he ‘ 
Puen: ee : ae a ; ea ie ed Ga ; ae Peper Source. [Upper trey ag fcantet | 
‘Example This example demonstrates a typical call to the Printer _ . | .Perrrsu : fevesvxiti” 1g oa 
Setup dialog box. The printer driver file name is ree |", == 3 


_ The ExtDeviceMode() function is accessed indirectly 


taining the procedure-instance address of the ExtDe- _ E 3 ea ee 
viceMode() function within the driver: The dialog box 


OJS dots perich 


trieved from the WIN.INI file using GetProfileString(). | 


- @ Portrait) 
4 159 dots per mch 


| © 308 dots pas inch 


from within the driver file by loading the diver, and ob--. oxen fF] 


Ld woidrettect 


will depend on the driver installed. Figure 10-8 shows a " Piguré 10. 8 ExtDeviceMode( ) 
typical example for the HP LaserJet printer driver. Example. 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


char 


"HANDLE 
DEVMODE 


szPrinter [64], szSysDir C128], szFullDriver £256], 
*szDriver, *szDevice, *szOutput ; : 

hpeiWees 

DevMode ; 


LPFNDEVMODE tpDeviceMode ; 


switch (iMessage) /* process windows messages */ 


t 


} 


ESCAPE 
Purpose 
Syntax 
Description 


case WM_COMMAND: /* process menu items */ 
switch (wParam) 
ft 
case IDM_DOIT: /* get driver name from WIN.INI */ 
GetProfileString ("windows", "device", "", 
szPrinter, 64) ; ae 
szDevice = strtok (szPrinter, ",") ; 
szDriver = strtok (NULL, ",") ; 
szOutput = strtok (NULL, ",") ; 
/* build full driver path/file Shee */ 
. GetSystemDirectory (szSysDir, 128) ; 
Lstrepy (szFullDriver, szSysDir) ; 
Lstreat (szFullDriver, "\\") ; 
Lstrcat (szFullOriver, szDriver) ; 
“lstreat (szFullDriver, "“.DRV") ; 
/* get handle to driver. */ 
hDriver = LoadLibrary (szFullDriver) ; 
if (hDriver > 31) 
{ Z./* call ExtDeviceMode() i adpReeety *] 
~ UpDeviceMode = (LPFNDEVMODE) 
GetProcAddress ChDriver, “ExtDeviceMode") ; 
- if (lpDeviceMode) 
(* LpDeviceMode) (hWnd, hDriver, &DevMode, 
eae i. szDevice, szOutput, NULL, NULL, 
ies DM_PROMPT) ; 


} 
else : 
MessageBox (hWnd, “Could nee load giver file.", 
“Message”, MB_OK) ; 
break : 
case IDM_QUIT: 
DestroyWindow ChWnd) - 
. break ; 
} 
break ; 
case WM_DESTROY: 
PostQuitMessage (0) ; 
break ; : 
default: : . 3 vo 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


mw Win2.0  mWin3.0 mWin3.1.1 - 


Sends special information to a device, such as a printer. 
‘int Escape(HDC hDC, int nEscape, int nCount, LPSTR lpInData, LPSTR IpOutData); 


The name “Escape” comes from the fact that many printers accept special sequences of data 
starting with the ASCII ESC character to signal special functions like form feeds and boldface 
printing. Windows has made this a general function, which can send a wide variety of messages to 
a device. Many of the Escape() functions supported under Windows versions 2.0 and 3.0 are not 
supported under versions 3.1 and later. Instead, the DeviceCapabilities(), GetDeviceCaps(), and 
ResetDC() functions have been added to provide.a better way to deal with the printer driver. 
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Uses - Most commonly used to communicate with a printer. 


Returns - int. The meaning depends on the nEscape message sent to the device. The value will be positive 
' ifthe function was successful. The most common negative (error) values are listed in Table 10-7. 


SP_ERROR General error. 


SP_OUTOFDISK The print spooler ran out of disk space. 
SP_OUTOFMEMORY The print spooler ran out of memory. 
SP_USERABORT The user killed the print job from the Print Manager window. 
Table 10-7, Escape() Return Codes. 
See Also GetDeviceCaps(), GetProfileString(), DeviceCapabilities(), GetDeviceCaps(), ResetDC() 
Parameters 
hDC HDC: The device context handle for the device to receive the message. 
nEscape int: One of the escape messages. See Table 10-8. 
nCount int: The number of bytes of data in the buffer pointed to by /p/nData. 
lpInData LPSTR: A pointer to the data buffer containing the information to send to the device. 
lpOutData LPSTR: A pointer to the data structure to receive data returned by the Escape() function call. 
Set to NULL if no data is returned. 
Common Escape Commands 


Escape (DC, STARTDOC, nCount, lpDocName, NULL) ; 


This starts a printing job. pDocName is a pointer to a string that contains the name that will 
show up in the Print Manager window for the job. The length of the string pointed to by /pDoc- 
Name is given in nCount. 


Escape (hDC, NEWFRAME, NULL, NULL, NULL) ; 

Ejects a page. 

Escape (kDC, ENDDOC, NULL, NULL, NULL) ; 

Ends a print job. 

Escape (hDC, ABORTDOC, NULL, NULL, NULL) ; 

Aborts the current printing job, erasing all pending data. 
Escape (hDC, SETABORTPROC, NULL, lpAbortFunc, NULL) ; 


Sets an abort procedure. /pAbortFunc is the procedure-instance address of the abort procedure. 
An example abort procedure is given in the introductory part of this chapter. 


Note Windows version 3.1 provides enhanced versions of these common escape functions. The equiva- 
lent functions under Windows versions 2.0 and 3.0 are listed in Table 10-8. 


_Windows Versions 2.0 and3.0 . ° Windows Version 3.1.~ 


ABORTDOC AbortDoc 
ENDDOC — EndDoe 
NEWFRAME | EndPage 
SETABORTPROG SetAbortProc 
STARTOOC = —SSSsCStat Do 


Table 10-8. Escape Function Version Reference. 
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The Windows 3.1 functions are used in the same manner as their predecessors. 


This example shows the minimum code necessary to output a line of text to the printer. A more 
complete example, including an abort procedure to stop printing, is included at the beginning of 
this chapter. The printer driver information is retrieved from the WIN.INI file using Get- 
ProfileString(). This information is used to create the printer device context. The Escape() func- 
tion is used to start the print job, eject a page, and end the print job. TextOut() is used to output 
the text string to the printer device context. 


tong FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


Hoc 
char - 


switch 
{ 


hoc ; 
szPrinter C641, *szDriver, *szDevice, *szOutput ; 


CiMessage) /* process windows messages */ 
g p ' 


case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
GetProfileString ("Windows", “device”, "", 
_szPrinter, 64) ; , ; 
szDevice = strtok (szPrinter, ",") ; 
szDriver = strtok (NULL, ",") ; 
szOutput = strtok (NULL, ",") ; 
hDC = CreateDC (szDriver, szDevice, szOutput, NULL) ; 
if (Escape (hDC, STARTDOC, 4, "Test", NULL) 
> 0) 
{ 
TextOut ChdC, 10, 10, 
“Output is on the printer.", 25) ; 
Escape (hDC, NEWFRAME, NULL, NULL, NULL) ; 
Escape (hDC, ENDDOC, NULL, NULL, NULL) -; 
} 
DeleteDC ChDC) ; 
break ; 


[Other program lines] 


ExtTextTOvut 


Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
hDC 2 


_ @Win2.0 @Win3d.0 mm Wind.) 


Controls text output within a rectangular area, with separate control over the spacing between 
each character. 


BOOL ExtTextOut(HDC hDG, int X, int ¥, WORD wOptions, LPRECT IpRect, LPSTR [pString, 
WORD nCount, LPINT lpDx); 


Similar to DrawText(), except that the character spacing can be set individually for the space 
between each character. 


Most often used with large titles or typefaces. If used with the SetTextAlign() function with 
wFlags set to TA_UPDATECP, the.X and Y parameters will be ignored. Instead, Windows will keep 
track of the ending location (current position) for each call to ExtTextOut() and start the next 
output there. 


BOOL. TRUE if the function outputs the string, FALSE on error. 
TextOut(), ee SetTextAlign() 


HDC: The output device context. Retrieved with GetDC() or BeginPaint(). 


E x . Ant: The logical X coordinate of the first character in the string. 


Y 


int: The logical Y coordinate of the first character i in the string. 
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wOptions _ - WORD: A combination of zero ) and o one or two of the eroptione in Table yy 9, combined with the C 
as Se dn language binary OR operator (|): te Ys os 


ET 70.4 CLIPPED | ~ The text is ae to fit it within the speed reclangle: 
~ ETO_OPAQUE The background of each character is opaque, covering up any graphics data undemeath the character. 
Table 10-9. ExtTextOut() Flags. 


lpRect , LPRECT: A pointer to a rectangle RECT structure. The rect- [il i : generic {~'|*. 
angle contains the dimensions of the clipping rectangle. Set to Do Itt Suit 


NULL if the ETO_CLIPPED style is not used. 


Test ee eA 


lpString LPSTR: A pointer to a string, containing the characters that 

will be output. Figure 10-9. ExtTextOut() 
nCount int: The number of characters inthe string = Example, | 
lpDx a | ~~ LPINT: A pointer to an ‘array of integers. Each element of the array ‘sets the sont of space 


between successive characters i in the string. [pDx is the space between the i and i+1 characters. 


Example ....__ This example, as shown in Figure 10-9, shows the use of ExtTextOut() to print a series of charac- 
ters with increasing amounts of space between each character. The character spacing is defined . 
in an array of integers, nSpace/]. 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


HOC ie" RDO; 


HFONT: -©° .° hFont- as 
RECT: . rTextRect ; ; 
int : nSpace.Ci = (10, 12, 14,16, 18, 20, 22, 24, 26, 28} ; 
static char cBuf CI = “Test Text" ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) ; 
case IDM_ DOIT: “. /* User hit the: “Do it” menu item ey 
SetRect CarTextRect, 10, 10, 200, 400) ; ss 
hDC = GetDC (hWnd) ; 
hFont = CreateFont (24, 0, 0, 0, 400, ‘0, 0, 0, OEM_CHARSET, 
OUT_DEFAULT. —PRECIS, CLIP DEFAULT. -PRECIS, 
PE FAULT_QUALITY, DEFAULT_PITCH | FF _MODERN, 
“modern") ; 
* SelectObject ChDC, hFont) ; 
ExtTextOut ChDC, 10, 10, ETO. CLIPPED | ETO _OPAQUE, 
&rTextRect, cBuf, strlen CcBuf), 
Saas oe ® CLPINT) Ni pales hs 
ae ; _.. ReleaseDC ChWnd, hoe) 4 
pve? « _ , pelersobject ChFont) ; 
ae ed break ; ; 
[Other program lines] 
GETBKCOLOR ite. en fou ll Win 2.0. .£Win3.0 mWin3.1 
Purpose \ ‘Determines the current haekeround color for a device context. 
Syntax a DWORD GetBkColor(HDC hDC);. - ia ee he, Sas 
_ Description | __ Windows can change the peau color using etka. Gekoot) allows you to find . 


out the current ene color. = 
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Uses 
Returns 


See Also 
Parameters 
hDC 


Example 
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Most often used with windows using the CS_OWNDC class style. 


DWORD, a 32-bit color value. Use the GetRValue(), GetG- 
Value() and GetBValue() macros to find the individual colors. 


GetBkMode(), SetBkColor(), SetBkMode() 


F generic [> [= 


HDC: The device context handle. 


The example shown in Figure 10-10 creates a window with its | 
own, private device context. The device context character Figure 10-10. GetBkColor() 
color, background mode, and background color are allsetwhen Example. 
the program starts running (WM_CREATE received). When the 
user clicks the “Do It!” menu item, the current background mode and Red, Green, and Blue color 
values are displayed. 

The class definition in the WinMain() function specifies a private device context for the 


window with the line 


wndclass.style = CS_HREDRAW |. cs. _VREDRAW | cs —OWNDC; 


Here is the top part of the WndProc() function. Because the window has a private device 
context, the device context settings are “remembered.” The changes made when processing the 


~ WM_CREATE messages will apply until another change is made, or until the application ter- 


. minates. ( 
long FAR FASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
HDC hDC ; 
int nBkMode ; 
DWORD dwBkColor ; 
char peut C10] ; ; 
switch CiMessage) - . . /* process windows messages */ 
case WM_CREATE: at rae as 
hDC = GetDOC ChWnd) ; /* owns DC - no need to release */ 
SetBkMode. (hDC, OPAQUE) ;° ' - {* opaque background */ 
SetBkColor (hDC, RGB (0, 255, 0)) ; ae green background */ 
Rigt hextCorer ChDC, RGB (255, 255, 255)) ; '/* white letters */ 
‘break ; 
case WM_ COMMAND: /* process menu items */ 
switch (wParam) 
case IDM | DOIT: | /* User hit the “Do it” menu item */ 
hDC = GetDC ChWnd) ; f 
nBkMode = GetBktode ChDC) ; 
4f (nBkMode == TRANSPARENT) 
TextOut (hDC, 10, 10, "TRANSPARENT", 11) ; 
else : 
TextOut (hDC, 10, 10, "OPAQUE", 6) ; 
dwBkColor = GetBkColor (hDC) ; . 
itoa (GetRValue (dwBkColor), cBuf, 10) ; . ! 
TextOut (hOC, 10, 30, cBuf, strlen (cBuf)) ; 
jitoa (GetGValue (dwBkColor), cBuf, 10) ; 
TextOut (hDC, 60, 30, cBuf, strlen (cBuf)) ; 
jitoa (GetBValue (dwBkColor), cBuf, 10) ; 
Texsdet ChDCc, 110, pne cBuf, strlen (cBuf)) ; 
break ; 
[Other program lines] 
GETBKMopDE mWin2.0 mWin30 gm Win3.1 
Purpose Determines the current background painting mode for a device context. 
Syntax int SeEBEMOdeHOG hDC); - 
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Description The background between characters, dashed lines, or hatched brushes can be either transparent 
_or opaque. The default mode for a device context is transparent. The background painting mode 
"is changed with SetBkMode(). Windows that have their own private device context can change 
the background painting mode anywhere in the program. This function allows you to find out the _ 
current background mode. 
Uses Most often used with windows using the OS_OWNDC class style. 
Returns int, either OPAQUE or TRANSPARENT. 
See Also SetBkColor(), SetBkMode(), GetBkColor() 
Parameters 
hDC HDC: The device context. 
Example See the previous example under GetBkColor(). 
GeTCHARWIDTH mWin2.0 mWin30 mWin3.1 
Purpose Determines the width of one or more characters in a font. 
. Syntax _ BOOL GetCharWidth(HDC ADC, WORD wFirstChar, WORD wlastChar, LPINT lpBuffer), 
Description This function finds the width of characters in the font currently selected into the device context. 
~ ~ Normally, a range of characters is written at one time into an array, so that the function only has 
to be called once. . 
Uses * Not often used. The GetTextExtent() function is more useful in determining the size of strings. 
Returns BOOL. TRUE if the character widths were determined, FALSE on error. 
See Also GetTextExtent() - 
Parameters 
hDC HDC: The device context handle for the DC containing the current font. Use a ik to 
add a font to the device context prior to calling GetCharWidth(). 
_ wFirstChar — WORD: The ASCH value of the first character in the font sequence. 
wLastChar WORD: The ASCII value of the last character in the font sequence. — 
lpBuffer LPINT: A pointer to an array of integers that will contain the character widths of all of the: 
characters between wFirstChar and wLastChar, inclusively. Be sure the array is large enough to. 
. | hold all of the elements. 
Example - This example creates a Modern font 24-logical units high. The size of all of the capital letters is 


placed in an array of integers nSpace// by using the GetCharWidth() function. In this example an 
“I” is eight units wide, while an “M” is 12 units wide. 


long FAR PASCAL WndProc CHWND hWnd, unsigned aa ad WORD wParam, LONG lParam) 
{ 


HDC hDC ; 

HFONT hone ; 

int. _nSpace [26] ; 
char cBuf £10] ; 


switch (iMessage) /* process windows messages */ 


case WM_COMMAND: 
switch (wParam) 


/* process menu items. */ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDCc ChWod) 3 . 
hFont = CreateFSnt (24, 0, 0, 0, 400, 0, 0, 0, - 
OEM_CHARSET, OUT_-DEFAULT_PRECIS, 
| CLIP_DEFAULT_PRECIS, DEFAULT_QUALITY, - 
DEFAULT_PITCH | FF_MODERN, 
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“modern") ; 

SelectObject (hDC, hFont) ; 
GetCharWidth (hDC, 'A', 'Z*, (LPINT) &nSpace) ; 
“TextOut (hoc, 10, 10, “I width =", 9) ; 
itoa ("I' - 'A', cBuf, 10) ; 

TextOut C(hDC, 80, 10, cBuf, strlen (cBuf)) ; 
TextOut (hdC, 10, 30,,"M width =", 9) ; 
itoa ('M' - 'A', cBuf, 10) ; 

TextOut (hoOC, 80, 30, cBuf, strlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 

DeleteObject ¢hFont) ; 


. break ; 
[Other program lines] 
GETDC | mWin2.0 mWin3.0  mWin31 
Purpose Retrieves a handle to the device context for the client area of a window. 
Syntax — ’ HDC GetDC(HWND hWnd); 
Description The attributes of the device context retrieved depend on the class upon which the window was 


based. For the common display context, GetDC() will use default values for the fonts, colors, etc. 
each time GetDC() is called. For class and private device contexts, the previous settings for the © 
device context are not changed. 
Uses Used prior to calling a GDI output function. GetDC(Q is used anywhere within a program except 
in processing WM_PAINT messages. Use BeginPaint() to retrieve the device context when paint- 
ing. When the GDI output is finished, use ReleaseDC() to free the device context so that it can be 
retrieved again by another part of the program. This is not necessary for class or private device 


contexts, 
Returns HDC, a handle to the device context of the window's client area. 
See Also BeginPaint(), ReleaseDC(Q), RegisterClass() 
Parameters 
hWnd HWND: A handle to the window containing the client area. 
Note A maximum of five device contexts can be open at one time. 
Example This program fragment uses GetDC() to retrieve the client area device context prior to printing 


text. A new font is created and selected into the device context, rather than using the default 
font. After the output is complete, both the font and device context are released. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC hoc ; 
HFONT hFont ; 
switch CiMessage) /*® process windows messages */ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
t 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
hDC = GetDC (hWnd) ; ; 
hFont = CreateFont (48, 0, 0, 0, 400, 0, 0, 0, 
OEM_CHARSET, OUT_DEFAULT_PRECIS, 

CLIP_DEFAULT_PRECIS, DEFAULT_QUALITY, - 
DEFAULT_PITCH | FF_ROMAN, . 
“roman") ; 

SelectObject (hDC, hFont) ; 

TextOut (hDC, 10, 10, “Text Output", 11) ; 

ReleaseDC (hWnd, hDC) ; 

DeleteObject (hFont) ; 

break ; 2 


[Other program lines] 
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GETDCOrcG mm Win2.0) a Win3.0  SWin3.! 

Purpose Determines the screen coordinates for the logical origin of the device context. 

Syntax . DWORD GetDCOrg(HDC hDC); 

Description GetDCOrg() determines the screen coordinates of the origin (0,0 point) of a device context. This 
function is equivalent to calling LPtoDP() for point 0,0 followed by saad 

Uses Mouse coordinates are frequently given in screen coordinates. S 


. This function allows you to compute where the mouse is rela- 


tive to a window. Do H! = Quit ; 


Returns DWORD. The low-order word contains theX position. The high- | 

- . order word contains the Y position. Origin = 154, 208 

See Also LPtoDPQ, ClientToScreen(), GetCursorPos() oa acide Seieasanal 
Parameters . . Figure 10-11. GetDCOrg() 
hDC _. . HDC: A handle to the window client area device context. Use Example. .— 


GetDCQ) to retrieve this value, unless the program is process- 
_. ing a WM _PAINT message. If so, use BeginPaint() to retrieve the hDC value. 
Related Messages WM _MOUSEMOVE, WM_LBUTTONDOWN, etc. 
Example _. The example shown in Figure 10-11 outputs the XY position of the origin of the window’s client 
_ area when the user clicks the “Do It!” menu item. The origin of the window's device context is 

» displaced by 20 units in both directions prior to getting the location of the origin in screen coor- 
~ dinates. The offset of the origin results in the TextOut() function’s output to logical coordinates 
0,0 to show up in client coordinates 20,20. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hDC ; 
DWORD dwOffset ; 
char cBuf C128] ; 
switch CiMessage) /* process windows messages */ 
{ i 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
HDC = GetDC ChWnd) ; 
SetWindowOrg (hDC, -20, -20) ; 
dwOffset = GetDCOrg ChDC).; 
TextOut (hDC, 0, 0, cBuf, wsprintf (cBuf, 

“Origin = %d, “d", LOWORD SSuOTISEt2, 
attmOeD (dw0ffset))) ; 

ReleaseDC (hWnd, hDC) ; 


' break ; 
[Other program lines] 
GeTDEVICECAPS Re os Win2.0 &Win30 mWin3l 
Purpose Determines the capabilities of a device. 
Syntax int GetDeviceCaps(HDC hDC, int ninden), 
Description Although Windows provides a good deal of device independence, it is sometimes necessary to 


‘determine the capabilities of the hardware Windows is using. GetDeviceCaps() can provide a 
wide range of information for any device that has a device context handle assigned to it. 


Uses Determining if a printer can display graphics, if the screen is monochrome or color, etc. 
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Returns int, the value of the device parameter specified by /ndez. 

See Also ’ CreateDC(), GetProfileString(), DeleteDC() 

Parameters 

hDC HDC: The device context handle. This can be to a printer, plotter, video, or memory device con- 
text. Retrieve this value with GetDC(), CreateICQ), CreateDCQ), ete. 

nIndex int: Specifies which value GetDeviceCaps is to obtain for the device. It can be any of the values 


listed in Table 10-10. 


| Index Meaning ei Dd] 


DRIVERVERSION The driver version number, 0x100 for version 1.0, 0x101 for version 1.01, etc. 
TECHNOLOGY Retums one of the following values: 
DT_PLOTTER Vector piotter. 


DT_RASDISPLAY Raster dispiay. 
DT_RASPRINTER Raster printer. 
DT_RASCAMERA Raster camera. 
DT_CHARSTREAM Character stream. 


DT_METAFILE Metafile. 
DT_DISPFILE Display file. 

HORZSIZE The approximate width of the display in millimeters. 

VERTSIZE The approximate height of the display in millimeters 

HORZRES The number of pixels horizontally. 

VERTRES The number of pixels vertically. 

LOGPIXELSX | The number of pixels per logical inch horizontally. 

LOGPIXELSY The number of pixels per logical inch vertically. 

BITSPIXEL The number of color bits per pixel. 

PLANES The number of color planes per pixel. 

NUMBRUSHES The number of device brushes. 

NUMPENS The number of device pens. 

NUMFONTS The number of device fonts. 

NUMCOLORS The number of colors the device supports. 

ASPECTX The relative width of a pixel as used for kine drawing. 

ASPECTY The relative height of a pixel as used for line drawing. 

ASPECTXY. The diagonal width of a pixel as used for line drawing. 

PDEVICESIZE The size of the PDEVICE internal data structure. - 

CLIPCAPS . Determines if the device can clip to. a rectangular region. Retums 1 if clipping can be done, Oifnot. . 

SIZEPALETTE The number of entries in the system palette. | 
_ NUMRESERVED . The number of reserved entries in the system palette. 


GOLORRES The number of bits of color information per pixel. 
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Table 10-10. continued 


RASTERCAPS The raster capabilities of the device. The returned value may contain any of the following binary 
values: ; 
RC_BANDING Requires that the output be banded (for example: dot matrix printers). 
. RC_BITBLT Can transfer bitmaps. | 


RC_BITMAP64 Can transfer bitmaps larger than 64K bytes. 
RC_DI_BITMAP Can support SetDIBits( )} and GetDiBits( ) functions. 
RC_DIBTODEV - Can support SetDIBitsToDevice{ } function. 
RC_FLOODFILL Cando flood fils. 

RC_GD120-°O8UTPUT Can support Windows 2.0. 

RC_PALETTE Palette-based device. 

-RC_SCALING Can do scaling. 

RC_STRETCHBLT — Can do StretchBit() function. 

RC_STRETCHDIB ~— Can do StretchDIBits{) function. 


CURVECAPS Returns a bit-coded value. Each bit is 1 if TRUE, 0 if FALSE. The bits have the following 
- meanings: : 
Bit 0 Can do circles. 
Bit 1 Can do pie wedges. 
Bit 2 Can do chord arcs. 
Bit 3 Can do ellipses. 
. Bit4 Can do wide borders. 
4 Bit 5 Can do styled borders. 
| Bit 6 Can do wide/styled borders. 
Bit 7 Can do interiors. | 
“UNECAPS Retums a bit-coded value. Each bit is 1 if TRUE, 0 if FALSE. The bits have the following 
meanings: - 
Bit 0 Reserved. 
Bit 1 Can do polyline. 
Bit 2. > Reserved. 
Bit 3 Reserved. 
Bit 4 Can do wide lines. 
Bit5 Can do styled lines. 
Bit 6 Can do wide + styled lines. 
Bit 7 Can do interiors. 
POLYGONALCAPS Retums a bit-coded value. Each bit is 1 if TRUE, 0 if FALSE. The bits have the following 
meanings: SF 
Bit 0 Can do altemate fill polygons. 
Bit 1 ~ Can do a rectangle. 
Bit 2 Can do winding number filled polygons. 
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- Bits Can do scan lines. 
Bit 4 __ Can do wide borders. 
Bit 5 Can do styled borders. 
Bit 6 Can do wide + styled borders. 
Bit 7 Can do interiors. 
TEXTCAPS Retums a bit-coded value. Each bit is 1 if TRUE, 0 if FALSE. The bits have the following 
meanings: 
Bit 0 Can do character output precision. 
Biti . Can do a stroke output precision. 
Bit 2 Can do stroke clip precision. 
Bit 3 Can do 90-degree character rotation. 
Bit 4 Can do any character rotation. 
Bit 5 Can do scaling independent of X and Y. 
Bit 6 Can do doubled character for scaling. 
Bit 7 Can do integer multiples of scaling. 
Bit 8 Can do any multiples for exact scaling. 
Bit9 ~ Can do double-weight characters. 
Bit 10 Can do italicizing. 
Bit 14 Can do underlining. 
Bit 12 Can do strikeouts. 
Bit 13 Can do raster fonts. 
Bit 14 Can do vector fonts. 
| Bit 15 Reserved. Must be returned zero. 
Table 10-10. GetDeviceCaps() Index Values. ; : = 
Example This example, shown in Figure 10- | [= sa genenc os 
12, determines the number of fonts |Dolt! Quit | 
and the horizontal resolution ofthe ¥4¥ 
Le ne eer | PCL/HP Laserset 
String(), which reads the WIN.INI Number aft fonts | 4 


file. A device context for the printer 
is created, and then GetDevice- 
Caps() determines the printer’s ca- fx SE : 

pabilities. Figure 10-12. GetDeviceCaps() Example. 


Number of dots per line 2400 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hDC ; 
char szPrinter C64], *szDriver, *szDevice, *szOutput, cBuf [10] ; 
int nFonts, nXPixels ; 3 ; 
switch CiMessage) /*®* process windows messages */ 
{ 
case WM_COMMAND: -/* process menu items */ 
switch (wParam) | 
{ 
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case IDH_DOIT: /* User hit the "Do it" menu item */ 
GetProfileString ("“Windows", "device", 
o"  szPrinter, 64) ; 
szDevice = strtok (szPrinter, ",") ; 
szDriver = strtok (NULL, ",") > 
szOutput = strtok (NULL, ",") >; 
hDC = CreateDC (szDriver, szDevice, szOutput, NULL) ; 
nFonts = GetDeviceCaps (hDC, NUMFONTS) ; 
nxPixels = GetDevicelaps ChDC, HORZRES) =: 
DeleteDC (hDC) ; 
hDC = GetDC (hWnd) ; 
TextOut (hDC, 10, 10, szPrinter, lstrlen (szPrinter)) ; 
jtoa (nFonts, cBuf, 10) ; 
TextOut C(hDC, 10, 30, “Number of fonts =", 16) ; 
TextOut (hDC, 150, 30, cBuf, Lstrlen (cBuf)) ; 
itoa (nXPixels, cBuf, 10) ; 
TextOut ChDC, 10, 50, 
"Number of dots per Line =", 24) ; 
TextOut ChDC, 170, 50, cBuf, Lstrlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 


break ; 
[Other program lines] 
_ GetTMarMope a | Win2.0 eWin3.0 sWin3.l 

Purpose Determines the mapping mode being used by a device context. 

Syntax int GetMapMode(HDC kDC); 

Description This function finds out which of the mapping modes is in effect for the given device context. 
Mapping modes are changed by SetMapMode(). 

Uses... Normally used with windows including the CS_OWNDC style. This allows the window to keep 
track of changes to the device context in its own private storage area for the DC. 

Returns The mapping mode. This can be: MM_ANISOTROPIC, MM_HIENGLISH, MM_HIMETRIC, 
MM_ISOTROPIC, MM_LOENGLISH, MM_LOMETRIC, MM_TEXT, or MM_TWIPS. 

See Also SetMapMode() contains explanations of the meaning of the different mapping modes. 

Parameters 

hDC HDC: The device context. 

Example This example checks the mapping mode of the devicc context every time a WM_PAINT message is 


received. The window’s class style must include the CS_OWNDC flag, so that changes to the de- 
vice context are not forgotten every time the DC is released. In WinMain(), 


‘yndclass «style = CS_HREDRAW | CS_VREDRAW | CS_OWNDC; 


In this simple example, clicking the “Do It!” menu item switches the device context to the 
MM_ LOMETRIC mode, but does nothing else. 


une FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD uparans LONG lParam) 
{ 


HDC hoc ; 
- PAINTSTRUCT ps ; 
int nMapMode ; 
POINT ptTextLoc ; 
switch CiMessage) /* process windows messages x]. 
C 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
nMapMode = GetNapMode (ps.hdc) ; 
if (nMapMode == MNM_TEXT) 
TextOut (Cps.hdc, 10, 10, "“MM_TEXT mode.", 13) 
else if (nMapMode == MM_LONETRIC)- 
{ 
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ptTextLoc.x = 10; 
ptTextLoc.y = 10 ; 
DPtoLP (ps.hdc, (LPPOINT) &ptTextLoc, 1) ; 
TextOut (ps.hdc, ptTextLoc.x, ptTextLoc.y, 
"MM_LOMETRIC mode.", 17) ; 
} 
EndPaint (hWnd, &ps) ; 
break ; 
case WM_COMNMAND: /*®* process menu items */ 
switch (wParam) 


case IDM_DOIT: . /* User hit the "Do it" menu item */ 
ADC = GetDC ChWnd) ; 
_SetMapMode ChDC, MM. | LOMETRIC) ; 
ReleaseDC ChWnd, hDC) ; 
InvalidateRect Chiind, NULL, TRUE) > /* force WM_PAINT */ 
UpdateWindow’ ChWnd) ; , 


break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 
} 
break ; - 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; ; 
default: /* default windows message processing */ 
‘ return DefWindowProc ChWnd, iMessage, wParam, LParam) ; 
} 
return (OL) >; 

} 

GETSYSTEMMETRICS oWin2.0 8Win3d.0 mWin31 

Purpose Retrieves the dimensions of different window items on the video display. 

Syntax int GetSystemMetrics(int nIndex); | 

Description - Depending on the type of computer and video hardware Windows is running on, different objects 
will have different sizes and capabilities. GetSystemMetrics() allows your app oaon program to 

. find out the values currently in use on the system. 

Uses In many cases, you can base the sizing of objects you will add to the client area in proportion to a 
value retrieved by GetSystemMetrics(). For example, if you are adding a scroll bar control, it will 
look best if the size matches the system metrics scroll bar dimensions. Window borders 
(SM_CXBORDER) also provide a good basis for the minimum line thickness that will be easily 
visible. 

Returns int, the value requested. 

Parameters - . 

nIndex int: Specifies which value GetSystemMetrics() is to retrieve. It can be any one of the values listed 


in Table 10-11. All screen-related sizes are given in device units (pixels). 


Meaning © Wig cat ae ee 
SM_CXDOUBLECLK win n3. 4) The second mouse click of a double-click sequence must fall within this range Shenae The 
width is measured in pixels around the location of the first mouse click. 


SM -CYDQUALECLK Win 3.1) The second mouse click of a double-click sequence must fall within this range-vertically. The 
width is measured in pixels around the location of the first mouse click. 


_ SM_CXICONSPACING (Win 3.1) The width of the rectangles that Windows uses to position tiled icons. 
SM_CYICONSPACING Win 3.1) The height of the rectangles that Windows uses to position tiled icons. 
_ SM_CXSCREEN The width of the screen. 
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Value © 
SM_CYSCREEN _ 
SM_CXFRAME 
SM_CYFRAME 
SM_CXVSCROLL 
SM_CYVSCROLL 
SM_CXHSCROLL 
SM_CYHSCROLL 
SM_CYCAPTION 
SM_CXBORDER 
SM_CYBORDER 
SM_CXDLGFRAME 
SM_CYDLGFRAME 
SM_CXHTHUMB 
SM_CYVTHUMB 
SM_CXICON 
SM_CYICON 
SM_CXCURSOR 
SM_CYCURSOR 

"SM_CYMENU 


Table 10-11. continued 


The height of the screen. 
The width of a window frame that can be sized. 


The height of a window frame that can be sized. 

The width of the arrow bitmap on a vertical scroll bar. 

The height of the arrow bitmap on ‘a vertical scroll bar. 

The width of the arrow bitmap on a horizontal scroll bar. 

The height of the arrow bitmap on a horzontal scroll bar. 

The height of the window caption. 

The width of a window border that cannot be sized. 

The height of a window border that cannot be sized. 

The width of a window frame for a window that has the WS_DLGFRAME style. 
The height of a window frame for a window that has the WS_DLGFRAME style. 
The width of the thumb bitmap on a horizontal scroll bar. 

The height of the thumb bitmap on a vertical scroll bar. 

The width of an icon. 

The height of an icon. 

The width of a cursor. 

The height of a cursor. 

The height of a single-line menu bar. 


SM_CXFULLSCREEN The width of a window client area when the window is maximized. 
SM_CYFULLSCREEN 


SM_CYKANJIWINDOW 


The height of a window client area when the window is maximized. 
The height of a Kanji window (Japanese character set). 


SM_CXMINTRACK The minimum tracking width of a window. 

SM_CYMINTRACK The minimum tracking height of a window. 

SM_CXMIN- The minimum width of a window. 

SM_CYMIN The minimum height of a window, — 

SM_CXSIZE __ The width of the bitmaps in the window title bar (minimize, etc.). 

SM_CYSIZE The height of the bitmaps in the window title bar (minimize, etc.). 
SM_MENUDROPALIGNMENT The alignment of popup menus. A value of zero means that the left side of a popup menu is 
(Win 3.1) aligned with the left side of the menu-bar item. A nonzero value means that the left side of the 


popup menu is aligned with the right side of the corresponding menu-bar item 
SM_MOUSEPRESENT TRUE if @ mouse is present, FALSE (zero) if not. 
SM_DEBUG TRUE if the debug version of Windows is running, FALSE if not. 
SM_SWAPBUTTON _ TRUE if the left and right mouse buttons have been switched, FALSE if not. 


Table 10-11. GetSystemMetrics() nIndex Values. 


Example This example puts a red border (line) in the center of the client area every time a WM_PAINT" 
message is received. The size of the line is computed equal to the width of a window border. This 
assures that the size will be reasonable on a wide range of video equipment. : 
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long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
PAINTSTRUCT ps; 
HPEN hPen ; 
int nFrameWide ; 
RECT rClient ; 
switch (iMessage) . /* process windows messages */ 
case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
nFrameWide = GetSystemMetrics CSM_CXFRAME) ; 
hPen = CreatePen (PS_SOLID, nFrameWide, RGB (255, 0, 0)) ; 
SelectObject (ps.hdc, hPen) ; 
GetWindowRect ChWnd, &rClient) ; 
MoveTo (ps.hdc, 0, nFrameWide/2) ; 
LineTo (ps.hdc, rClient.right, nFrameWide/2) ; 
DeleteObject (hPen) ; 
EndPaint (hWnd, &ps) ; 
break ; 
[Other program lines] 
GETTABBEDTEXTEXTENT _ OWin2.0 mWin30 mWin31 
Purpose Determines the logical dimensions of a string containiig tab characters. 
Syntax DWORD GetTabbedTextExtent(HDC hDC, LPSTR IpString, int nCount, int nTabPositions, 
LFINT lpnTabStopPositions); 
Description Similar to GetTextExtent(), except that it will correctly expand tab stops. 
Uses Sizing objects on the screen to match a tabbed text string. Used in conjunction with Tabbed- 
TextOut(). Some devices do not put characters in regular sized character cells. These devices do 
“kerning” to optimize character spacing. GetTabbedTextExtent() will not return the correct text 
extend on devices that do kerning. . 
Returns DWORD. The low-order word contains the width of the string in logical units. The hig -order 
word contains the height of the string in logical units. 
See Also TabbedTextOut(), GetTextExtent() 
. Parameters 
“hDC HDC: The device context. 
lpString - LPSTR: A pointer to a character string that will be output. 
—nCount int: The number of characters, including tab characters, in the string. 
nTabPositions int: The number of tab positions specified in lpnTabStopPositions. lf set to 0 and_lpnTab- 


StopPositions is NULL, tabs are expanded to an even eight average character widths. If set to 1, 
tabs are expanded to an even spacing specified by the first element of the lpnTabStop Positions 
array. 


lpn TabStopPositions LPINT: A pointer to an array of integers, holding the tab stop positions. The tab positions are 


Example 


measured in device units (pixels) and must be in ascending order. 


This example WndProc() fragment outputs a tabbed text string, and then underlines the string 
with a red line, The dimensions and location of the line are calculated based on the text dimen- 
sions, GetTabbedTextExtent() is not strictly necessary in this example, as TabbedTextOut() 1 re- 
turns the same height and width values. 


Long FAR PASCAL WndProc CHWNbD hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{. 


HDC 


static 
static 


— hoe > : 
char epee Cl = {"First - Paetd 1\tField ivast Field") ; a 
int ntabs C1 = (30, 45, 60} ; ; a 3 
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sep 
al 


 (pwORD ' dwTextSize ; 


‘HPEN hPen ; 
switch (iMessage) /* process windows messages */ 
t 
case WM_COMMAND: /* process menu items -*/ 


switch (wParam) 
{ 


' case IDM_DOIT: /* User hit the “Do it" menu item */ 

hDC = GetDC ChWnd) ; 

TabbedTextOut (hDC, 10, 10, cBuf, strlen (cBuf), 3 
(LPINT) &nTabs, 10) ; 

dwTextSize = GetTabbedTextExtent (hDC, cBuf, 
strlen (cBuf), 3, (LPINT) &nTabs) ; 

hPen = CreatePen (PS_SOLID, HIWORD (dwTextSize) / 2, 
RGB (255, 0, 0)) ; 

SelectObject ChDC, hPen) ; 

MoveTo (hDC, 10, 10 + (2 * HIWORD (dwTextSize))) ; 

LineTo ChDC, 10 + LOWORD (dwTextSize), 
10 + (2 * HEWORD SduTEXESIZ€222\2 

DeleteObject (hPen) ; 

: ReleaseDC ChwWnd, noe) ; 


' break ; 
[Other program lines] 
GETTEXTALIGN | ‘me Win2.0 mWin30 mWin3.1 
Purpose Determines the text alignment settings of a device context. 
Syritax \ WORD GetTextAlign(HDC kDC); _ | 
Description The text alignment settings are set with the SetTextAlign() fi function. These settings determine 
= _ how the X, Y parameters passed with the TextOut() and ExtTextOut() functions are interpreted. 
Uses - Used with windows created with a private device context. The text alignment settings are then 
“remembered” by the device context. 
Returns One or more of the flags in Table 10-12. 


TA_BASELINE The baseline of the first character is used to specify the string position. 
TA_BOTTOM The bottom of the first character is used to specify the string position. 


TA_CENTER - The center of the first character is used to specify the string position. 
TA_LEFT ‘ The left side of the first character is used to specify the string position. 
TA_NOUPDATECP The location at the end of the last text output is not saved. 

TA_RIGHT. The right side of the first character is used to specify the string position. 
TA_TOP The top of the first character is used to specify the string position. 


TA_UPDATECP The position at the end of the last text output is saved. The next call to TextOut() or ExtTextOut( ) will start 
from this location, ignoring the X,Y data in the output function parameters. 


Table 10-12. GetTextAlign() Flags. 


Note The default values for a device context are TA_LEFT, TA_TOP, and TA_LNOUPDATECP. The TA_ 
' flags are not defined in WINDOWS.H as unique binary values. It is necessary to break the three 
types of flags into groups, and then compare each group with the flag values. The example shows 

how this is done. 


See Also etTextAlign(), TextOut(), ExtTextOutQ). 


Sh 
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Parameters 
hDC HDC: The device context. 
Example This example shows how to process the returned value from GetTextAlign(). This function is 


useful only when a window i is created with its own private device context. This means that the 
class definition will include the CS! OWNDC style in the WinMain() function. 


wndclass.style = CS_HREDRAW | CS_VREDRAW | CS_OWNDC ; 
In this excerpt from a WndProc() function, the text alignment is set when the program first 


starts (WM_CREATE message received). When the user clicks the “Do It!” menu item, the text 


alignment values are determined via a series of switch statements and output to the device con- 
text. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC . hdc ; 
WORD wALlign ; 
switch (iMessage) /* process windows messages */ 
{ ; 
case WM_CREATE: 
hDC = GetDC (hWnd) ; /* owns DC, no need to release */ 
SetTextAlign (hDC, TA_BOTTOM | TA_LEFT) ; 
break >; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 


hDC = GetDC ChWnd) ; 

wAlign = GetTextAlign ChDC) ; 

switch (wAlign & (TA_LEFT | TA_CENTER | TA_RIGHT)) 
{ 7 


case TA_LEFT: 
TextOut (hDC, 10, 20, "LEFT", 4) ; 
break ; 

case TA_CENTER: 
TextOut ChOC, 10, 20, "CENTER", 6) ; 
break ; 

default: 
TextOut ChdC, 10, 20, "RIGHT", 5) ; 

break; : 

} 


‘ ‘ 
switch (wALign & (TA_TOP { TA_BOTTOM | TA_BASELINE)) 
{ 


case TA_TOP: 
TextOut (hdc, 10, 40, “TOP", 3) 
break ; 

case TA_CENTER: 
TextOut (hDC, 10, 40, "BOTTOM", 6) 
break ; 

default: 
TextOut (hDC, 10, 40, "BASELINE", 8) ; 
break ; 


. 
7 


. 
a 


}. 
switch (wALign & TA_UPDATECP) 
{ 


case TA_UPDATECP: 
TextOut (hDC, 10, 60, "UPDATECP", 8) ; 


break ; 
default: 
TextOut ChDC, 10, 60, "NO UPDATECP", 11) ; 
break ; 
} 
break ; 


[Other program lines] 
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GETTEXTCHARACTEREXTRA | BWin2.0 mWin30 mWin3.1 
- Purpose Determines the amount of extra character spacing defined for a device context. 
Syntax int GetTextCharacterExtra(HDC hDC); 
Description The SetTextCharacterExtra() function is used to add extra space between letters output by 
: TextOut() and ExtTextOut(). GetTextCharacterExtra() is used to find out how much extra space 
is defined for a device context. 7 
Uses: Use with windows that have a private device context defined as part of their class definition. . 
Returns int, the amount of extra space between characters, measured in logical units. 
See Also SetTextCharacterExtra(), TextOut(), ExtTextOut(), GetMapMode() 
Parameters 
hDC HDC: The device context handle. __ 
This function is useful only if the window has its own private device context. This means that the 


CS_OWNDC style will be part of the window's class definition in the WinMain() function. 
wndclass.style = CS_HREDRAW | CS_VREDRAW | CS_OWNDC ; 


This example sets 10 extra units of space between characters when the program starts (re- 


- ceives a WM_CREATE message). Because the default mapping mode MM_TEXT is used, the space 


equates to 10 pixel widths. When the user clicks the “Do It!” menu item, the program checks 
whether the extra space is still defined. Because this window has its own private device context, 
the response will always be “Extra spacing.” 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC 
int 


hOC ; 
nSpaceExtra ; 


switch (iMessage) . nw he process windows messages */ 
t 


case WM_CREATE: . . 
hDC = GetDC ChWnd) ; '/* owns DC, no need to release */ 
SetTextCharacterExtra (hDC, 10) ; 

break ; 
case WM_COMMAND: ; /* process menu items */ 
switch (wParam) ; 

case IDM_DOIT: /* User hit the “Do it" menu item */ 
hDC = GetDC (hWnd) > : 
nSpaceExtra = GetTextCharacterExtra (hDC) ; 
if (nSpaceExtra == 0) 

TextOut (hdc, 10, 10, “Normal spacing.", 15) ; 
else : 

TextOut (hDC, 10, 10, “Extra spacing.", 14) ; 

break ; A 


[Other program lines] 


GETTEXTCOLOR mWin2.0 mWin30 mWin31 


Purpose 
Syntax 
Description 


Uses 
Returns 


Retrieves the text color setting for a device context. 
DWORD GetTextColor(HDC hDC); 


The default text color for a device context is black. This can be changed with SetTextColor(). The 
color remains effective until a call to SetTextColor() changes the value. GetTextColor( allows: 
the program to determine the current text color. 


Use with windows that have their own private device context. 
The 32 bit color value for the current text color.. 
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Parameters 
ADC 
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~ SetTextColor(), SetBkColor(), GeLBk Color) SetBkMode(), GetRValue(), GetGValue(), 


GetBValue() 


| Mei! generic | [= 

HDC: The device context handle. 
The example in Figure 10-13 has a window with a private de- 
vice context. When the program starts (WM_CREATE message 
received), the text color is set to blue. Whentheuserclicksthe Figure 10-18. SetTextColor() 
“Do It!” menu item, the current color value is output in hexa- and GetTextColor() Example. 
decimal. . | 

The window's class definition in WinMain() includes the CS_OWNDC style, giving the win- 
dow its own private device context: 


wndclass.style = CS_HREDRAW | CS_VREDRAW | CS_OWNDC ; 


Note that the RGB macro parameters are in the opposite order of the storage order inside the 
32-bit coded color value (compare RGB (0,0,255) with the output value of OxFF0000). 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


HDC hdc ; 
DWORD dwiextColor ; 
char cBuf £101 ; 
switch (iMessage) /* process windows messages */ 
case WM_CREATE: 
hDC = GetDC ChWnd) ; /* owns DC, no need to release */ 
SetTextColor (hDC, RGB (0, 0, 255)) ; /* blue 'etters */ 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
case IDM_DOIT: /* User hit the “Do it" menu item */ 
hDC = GetDC ChWnd) ; 
dwTextColor = GetTextColor ChDC) ; 
Ltoa CdwTextColor, cBuf, 16) ; /*® convert to hex */ 
_ TextOut Choc, 10, 10, "My Text Color =", 15> ; 
TextOut (hDC, 150, 10, cBuf, Istrlen CcBuf)) ; 
break ; 

[Other program lines] 

GeTTEXTEXTENT mWin2.0 mWin3.0 mWin3.1 

Purpose Determines the length of a string when it is output to a device context. 

Syntax DWORD GetTextExtent(HDC ADC, LPSTR lpString, int nCount); 

Description The text extent is the width of a string. The width is computed using the currently selected font. 
In the default MM_TEXT mapping mode, the width is in device units (pixels). If another mapping 
mode has been set with SetMapMode(), the width will be determined in logical units. Some de- 
vices do not put characters in regular sized character cells. These devices do: “kerning” to opti- 
mize character spacing. GetTabbedTextExtent() will not return the correct’ text extend on 
devices that do kerning. 

Uses This function is a direct way to calculate the size of a string prior to output. It also works directly 

: with SetTextJustification() to justify string output (see example). 

Returns DWORD. The low-order word contains the width. The high-order word contains the length. 

See Also SetTextJustification(), GetTabbedTextExtent() 

Parameters 

hDC HDC: The device context handle. 
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lpString 
nCount 


Example 


LPSTRING: A pointer to a character string. 
int: The number of characters in the string pointed to by 
lpString. 


This example justifies a aie -word string to fit exactly within . 
the bounds of a 200 pixel wide rectangle, see Figure 10-14. ° : 
GetTextExtent() is used to calculate the size of the string prior Figure 10-14. Text 


hed SRS SUNT ACERT net oe MRE Shel TET) 
[= Lok A GENOME. i SY Pe, 


String To 


to justification. SetTextJustification() then addsenoughspace Justification Example. 
. to expand the string to the full 200 unit size. The next call to 
" TextOut() uses the justification during output to space the words. 


With thissimple example, the number of spaces in the string (two) is known. Normally, you 
would have to check the number of spaces (break characters) in the string before calling 
SetTextJustification(). of 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : 


HDC hdc ; 
HPEN hPen ; 
DWORD dwExtent ; 
char cBuf C1 = {"String To Fit"} ; 
switch (iMessage) /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
case IDM_DOIT: /*. User hit the "Do it" menu item */ 
HDC = GetDC (hWnd) ; 
SetBkMode (hDC, TRANSPARENT) ; 
hPen = GetStockObject (BLACK_PEN) ; 
SelectObject (hDC, hPen) ; 
_ Rectangle (hDC, 10, 10, 210, 50) ; 
dwExtent = GetTextéExtent sehDes cBuf, 
Ustrlen (cBuf)) ; 
SetTextJustification choc, 200 - 
LOWORDCdwExtent), 2) ; 
TextOut ChDC, 10, 20,: cBuf, Lstrlen (cBuf)) ; 
_ReleaseDC ChWnd, hDC) ; 
break ; 
[Other program lines] 
GETTEXTFACE | . . mWin2.0 Win3.0° mWin3.1 
Purpose Retrieves the name of the current typeface. 
Syntax . int, GetTextFace(HDC hDC, int nCount, LPSTR lpFacename); 
Description The default typeface for a device context is the system font. If another font is selected, 
wae GetTextFace() will retrieve its name as a null-terminated string. 
Returns ‘int. The number of characters copied to the lpFacename buffer 
' See Also EnumFonts(), CreateFont(), CreateFontIndirect() 
Parameters 
hDC HDC: The device context handle. 
nCount int: The maximum number of characters to copy to the lpFacename buffer. 
lpFacename LPSTR: A pointer to a character buffer to hold the typeface name. 
Example This example outputs the name of the current typeface to the window’s client area when the user 


- Clicks the “Do It!” menu item. Because no other font has been selected, the program will display 


“system,” for the default system font. 
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long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ nee 


HDC hoc ; 

char cBuf £30] ; 

switch CiMessage) /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 
¢ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC (hWnd) ; 
GetTextFace (hDC, 29, cBuf) ; 
TextOut (hdc, 10, 10, cBuf, lstrlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 


break ; 
[Other program lines] i 
GeETTEXTMETRICS Win2.0 mWin30 mWin3.1 
Purpose Retrieves basic data about the font currently selected for a device context. 
Syntax BOOL GetTextMetrics(HDC hDC, LPTEXTMETRIC [pMetrics); . 
Description Retrieves data on a font by filling a TEXTMETRIC data structure. WINDOWS.H includes the fol- 


lowing definition of the TEXTMETRIC data structure 


typedef struct tagTEXTHETRIC 
me, 3 

int tmHeight; 

int. tmAscent; 

int tmDescent; 

int tmInternalLeading; 

int tmExternalLeading; 

int tmAveCharWidth; 

int tmMaxCharWidth; 

int tmWeight; . - 

BYTE tmitalic; 

BYTE tmUnderlined; 

BYTE tmStruckOut; 

BYTE tmFirstChar; 

BYTE: tmLastChar; 

BYTE tmDefaultChar; 

BYTE. tmBreakChar; 

BYTE tmPitchAndFamily; 

BYTE tmCharSet; 

int tmOverhang; 

int tmDigitizedAspectx; 

int tmDigitizedAspectY; 

} TEXTMETRIC; 


typedef TEXTMETRIC *PTEXTMETRIC; 
typedef TEXTMETRIC NEAR . *NPTEXTMETRIC; 


typedef TEXTMETRIC FAR *LPTEXTMETRIC; 


GetTextMetrics() fills in all of these values into a memory area pointed to by lpMetrics. 
Most commonly used to determine the height of the font. Sum the imHeight and tmExternal 


Uses 

leading elements to determine the total height of a font. 
Returns -BOOL. Nonzero if the function was successful, zero on error. 
See Also GetTextExtent(). 
Parameters ae 
hDC HDC: The device context handle. 
lpMetrics LPTEXTMETRIC: A pointer to a TEXTMETRIC data structure. 
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Example 


This example shows the most common use of GetTextMetrics(). The émHeight and tmExternal 
leading elements total to the height of the font. The font height is used to set the line spacing. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


c 
HDC 


HFONT 
int 


TEXTMETRIC . tm ; 


nDC ; 


hFont ; 
nLineSpace ; 


switch CiMessage) /* process windows messages */ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
hDC = GetDC ChWnd) ; 
hFont = CreateFont (24, 16, 0, 0, 700, 0, 0, 0, 
OEM_CHARSET, OUT_DEFAULT_PRECIS, 
CLIP_DEFAULT_PRECIS, DEFAULT meu aeL IN 
DEFAULT_PITCH | FF —MODERN, emodenan).g 
SelectObject (hDC, hFont) ; : 
'GetTextMetrics ChDC, &tm) ; 
nLineSpace = tm.tmHeight + 
. tm. tmExternalLeading ; 
TextOut C(hDC, 0, nLineSpace, 
' "These lines are", 15) ; 
TextOut Choc, 0, 2 * nLineSpace, 
“evenly spaced. ", 14) ; 
DeleteObject (hFont) ; 
ReleaseDC ChWind, hDC) ; 
break ; 


[Other program lines] 


GETVIEWPORTEXT wWin2.0 w8Win30 em Win3.l 


Purpose 
Syntax 
Description 


Uses 
Returns 


See Also 


- Parameters 


hDC 
Example 


Used with GetWindowExt() to determine the scale of the device context. 
DWORD GetViewportExt(HDC hDC); 


. The MM_ISOTROPIC and MM_ANISOTROPIC mapping modes allow the logical coordinate sys- 


tem of a device context to be any arbitrary scaled ratio to the physical device. GetViewportExt() 
and GetWindowExt() are used together to determine the current scaling. The scaling factor is 
the ratio of the viewport extent divided by the window extent. For example, if the viewport X 
extent is three, and the window X extent is one, the logical coordinate system expands all hori- 
zontal dimensions by a factor of three. If the signs of the viewport and window extents match, the 
coordinate orientation is unchanged. If one of the signs is negative and the other positive, the 
orientation is reversed. Reversing one sign is commonly used to make the Y values i increase up- 
ward, rather than the default system where Y values increase downward. 


Used with windows created with the CS_OWNDC class style that maintain a eae copy of their 
device context. 

DWORD, the viewport extent. The low-order word contains the X value. The high-order word 
contains the Yvalue. |, 

GetWindowExt(), SetViewportExt(), SetMapMode(, aa a 

| 

HDC: The device context handle. f ; 
This example creates a window with its own private device context. This means that the class 
style CS_OWNDC is specified in the WinMain() function. 


wndclass.style = CS_HREDRAW |-CS_VREDRAW | cs_OWNDC : 
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The program sets up the MM_ISOTROPIC mapping mode during startup (when the 
WM_CREATE message is received). The scaling is fixed at two logical units to one device unit by 
the SetWindowExt() and SetViewportExt() function calls. The Y axis orientation is reversed, so 
that Y values increase upwards by specifying a negative Y value in SetViewportExt(), while the Y 
value in SetWindowExt() is positive. When the user clicks the “Do It!” menu item, the current Y 
axis scaling is determined by comparing the values returned by GetViewportExt() and 
GetWindowExt(). The settings are displayed on the window's client area using TextOut(). Note 
that the Y values for TextOut() are set negative to make the text visible. This is because the 
logical origin has not been changed from the default upper left corner of the client area, and Y 
values now increase enerwant 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
4 ~ 


HDC hDC ; 
DWORD dwViewExt, dwWindExt ; 
~ switch CiMessage) /* process windows messages */ 


case WM_CREATE: 
hDC = GetDC ChWnd) ; 
SetMapMode (hDC, MM_ISOTROPIC) ; 
SetWindowExt (hOC, 1, 1) ; 
SetViewportExt (hDC, 2, -2) >: 
break ; ' 
case WM_COMMAND: /* process menu items */ 
; switch (wParam) 
{ 
case IOM_DOIT: /* User hit the "Do it" menu item */ 
hoc = Getoc ChwWnd) ; 
dwViewExt = GetViewportExt cnp G27 
dwWindExt = GetWindowExt ChDC) 7 
if Cabs CHIWORD (dwVfiewExt)) = 


abs CHIWORD (duindExt))) ; : 
{ 
TextOut Choc, 10, -10, 
“Device Y = Logical Y size", 25) : 
> 


else if Cabs (HIWORD (dwViewExt)) < 
abs SH INORD (dwWindExt))) 


{ 
, “Textout Choc, 10, -10, 
“Logical Y < Device Y size", 25) ; 
} 
‘ else 
{ . 


TextOut (hdc, 10, -10, 
“Logical Y¥ > Device Y size", 25) ; 


} 
if CCCint) HIWORD CdwViewExt) <0 && 
Cint) HIWORD (dwWindExt) > 0) JI 
CCint) HIWORD (dwViewExt) > 0 && 
Cint) HIWORD (dwWindExt) < 0)) 


{ 
TextOut (hDC, 10, -30, 
“Y axis increases upward.”, 24) ; 
} 
. else 
fs 
TextOut Choc, 10, -30, 
“y axis IncESsses downward.” ’ 26) ; 
} 
break 


[Other program lines] 
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GETVIEWPORTORG | : mWin2.0 wWin3.0 mWin3l 


a 

Purpose. Used with GetWindowOrg() to determine the location of the originoft the logical coordinate oe 
tem of a device context. 

Syntax a DWORD GetViewportOrg(HDC hDC); 

Description Windows allows two offsets to be applied to the.origin (0,0 location) of the logical coordinate 


system. SetWindowOrg() sets up the first offset, called the “window origin.” SetViewportOrg() 
sets up the second offset, called the “viewport origin.” The viewport origin is relative to the 
‘window origin, so you can think of the viewport origin as an offset from another offset. 


Uses. ts Used with windows that maintain their own private device context. 

Returns DWORD. The low-order word contains the X offset. The high-order word contains the Y offset. 

See Also ~- GetWindowOrg(), SetViewportOrg(), SetWindowOrg(), SetMapMode(), SetViewportExt(), 
SetWindowExt() 

Parameters 

hDC HDC: The device context handle. 

Note The scaling (GetViewportExt(), GetWindowExt()) and origin (GetViewportOrg(), Get- 


WindowOrg()) of a device context determine the difference between device coordinates and 
logical coordinates. The following formulas relate device points (DP) and logical points (LP): 


DP = Scale * (LP - WindOrg) + ViewOrg ; 
LP = (1/Scale) * (DP - ViewOrg) + WneOres: : 


. . Where: | 
Scale = ViewportExtent / WindowExtent ; 
Example © The example shown in Figure 10-15 creates a window withits J ; 
oO own private device context. Every time a WM_SIZE message is Window Org'= 


« i 7 : 3 . Org = 
received, the program resets the logical device scaling and ori- Viewton Ory 


gins. The MM_ISOTROPIC mapping mode is used. The scaling Figure 10-15. GetWindow- 

doubles the logical vertical size and reverses the Ydirectionso Org() and Genny 

that Y values increase upward on the client area. The Example. 

viewport origin is set equal to the lower left corner of the win- 

dow. The size of the client area is found by looking at the HIWORD of the lParam value ae 

with the WM_SIZE message. Because the window origin is always offset by 10 units in both theX 

and ¥ directions using SetWindowOrg(), the viewport origin appears at a location 10 units above 

and to the right of the lower left corner. (The viewport origin is always relative to the window — 

origin.) 

_  Theupper left corner of the letter V on the bottom line is the logical location 0,0 in the device 

context coordinate system. The upper left corner of the capital W on the upper text line is at 

logical location 0,10. The private device context for the window i is established in the WinMain() 

' function as part of the class definition. 


wndclass.style = cs_, HREDRAW ‘| CS_VREDRAW [| CS_OWNDC ; 


The output of the window and viewport offset values occurs when the user clicks the “Do It!” 
menu item. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
sf = 


HDC hDC ; 

DWORD dwvteworg, dwWind0rg. : 

char ' - eBuf £10 

switch CiMessage) /* process windows messages */ 


ee 
case WM_SIZE: : 
hDC = GetDC ChWnd) ; /* owns DC, no need to release */ 
SetMapMode (hDC, MM_ISOTROPIC) ; 
SetWindowExt (hDC, 1, 1) ; ; 
SetViewportExt (hDC, 2, -2) ; 
SetWindowOrg (hDC, -10, -10) ; 
SetViewportOrg (hDC, 0, HIWORD (LParam)) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
y 
case IDM_DOIT: hal User hit the “Do it" menu item */ 
DC = GetDC (hWnd) ; 
* dwViewOrg = Gotuteunerkana ChDC) >; 
dwWindOrg = GetWindowOrg ChDC) ; 
TextOut (hdC, 0, 0, “ViewPort Org =", 14) ; 
itoa CLOWORD (dwViewOrg), cBuf, 10)'; 
TextOut (hDC, 60, 0, cBuf, Lstrlen (cBuf)) ; 
TextOut (hDdDC, 70, 0, ",", 1) ; 
jtoa CHIWORD (CdwViewOrg), cBuf, 10) ; 
TextOut (hdc, 80, 0, cBuf, Lstrlen (cBuf)) ; 
TextOut ChDC, 0, 10, "Window Org =", 12) ; 
itoa (LOWORD (dwWindOrg), cBuf, 10) ; 
TextOut (hDC, 60, 10, cBuf, Lstrlen (cBuf)) ; 
-TextOut (hDC, 70,710, 23"5- 1:2 
itoa CHIWORD (dwWindorg), cBuf, 10) ; 
~ TextOut (hDC, 80, 10, cBuf, Istrlen (cBuf)) ; 
break ; 
[Other program lines] 
GETWINDOWwDC mWin2.0 mWin30  mWin3t 
Parpose . Retrieves the device context for the entire window, including the nonclient areas like the caption 
bar, scroll bars, borders, system menu button, etc. 
Syntax HDC GetWindowDC(HWND hWnd); 
Description This function allows a program to paint on the nonclient areas of a window. This is normally not 
necessary or desirable, as Windows automatically maintains the client area as part of the 
DefWindowProc() function operations. 
Uses Use of this function is generally discouraged. You can use it to create custom window types, but 
they will not conform to normal Windows conventions. 
Returns HDC, the device context for the window. oH oT z 
See Also GetDC(), BeginPaint() : 
Parameters ee Ss 
hWnd _ HWND: The window handle. 
Related Messages WM_NCPAINT, WM_PAINT, WM_NCACTIVATE 
Example - The example shown. in Figure 10-16 is one of the most complex 


_ in the book. The main window creates a new popup window 
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which has a separate class and a separate message processing 
function. The popup window intercepts WM_NCPAINT mes- 
sages in order to paint its own frame. The frame is drawn in Figure 10-16. 
red, with a fixed caption “Custom Frame.” WM_NCACTIVATE GetWindowDC() Example. 
and WM_PAINT messages must also be processed to avoid in- 
terference with the custom frame during the default windows processing. 

The ChildProc() message processing function must be listed in the EXPORTS section of the 


. program’s .DEF definition file. A function prototype must also be included a the pagent S 


header file. 
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Long | FAR PASCAL WndProc CHWND hWnd, Sisigned ilessuga; WORD wParam, LONG lParam) 
{ 


“HDC © te hDC ; : 
static ede wndclass ; /* the window class */ 
static HWND ; hPopup, hParent ; 


switch (iMessage) /* process windows messages */ 


. "case WM_CREATE: -,/* build the child window when program starts */ 
wndclass.style |, : = CS_HREDRAW | CS_VREDRAW | 
CS_PARENTDC ; 


wndclass.tpfnWndProc ChildProc ; 


wndclass.hbrBackground 
_wndclass.lpszMenuName 
_ wndclass.lpszClassName = “SecondClass" ; 
; . /* register the window class */ 
if(RegisterClass (&wndclass)) 


GetStockObject (WHITE BRUSH) 


c— 4 
.wndclass.cbClsExtra =0; 
wndclass.cbWndExtra . =O; 
wndclass.hInstance -= ghInstance ; 
wndclass.hIcon = NULL ; 
wndclass.hCursor = LoadCursor (NULL, IDC _ARROW) ; 


hPopup = CreateWindow ("SecondClass", "", 
. WS_POPUP | WS_VISIBLE | WS_BORDER } 
: WS_CAPTION, 
10, 50, 200, 150, hind, NULL, ghInstance, NULL ; 
ae ShowWindow ChPopup, SW_SHOW) ; 
} ; _ 
break ; 
case WM_COMMAND: _/* process menu items */ 
switch (wParam) 
t 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hParent = GetParent (hPopup) ; 
SendMessage (hPopup, WM_USER, hParent, OL) ; 
break ; 

case IDM_QUIT: /* send end bl application message */ 

Bos DestroyWindow. (hWnd) ; 


break ; 
} Ros 
a break ; 
Mae case WM_DESTROY: /* stop application */ 
sek PostQuitMessage (0) ; : 
* break ; 
default: : /* default windows message processing */ 


- return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 
} a , i 
return (COL) ; 
vo -x° SS ae Bt gu HE 
/* Here is a separate message processing procedure for the popup window */ 


Long FAR PASCAL ChildProc CHWND hPopup, unsigned iMessage, WORD wParam, LONG lParam) 
4 2 


HOC . hdc ; 

HPEN hPen ; : 

RECT rBorder, rClient ; 

switch (iMessage) yt ete so /* process windows messages */ 
case WM LNCPAINTs — /* nonclient area needs painting */ 


hDC = GetWindowDC ChPopup) ; 

GetWindowRect (hPopup, CLPRECT) &rBorder) ; 
SelectObject (hDC, GetStockObject (WHITE_BRUSH)) ; 
Rectangle (hDC,.0, 0, rBorder.right - rBorder.left, 


NULL ; > 


\ 
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rBorder .bottom - rBorder.top) ; 
hPen = CreatePen (PS SOLID, 5, RGB (255, 0, O)) ; 
SetectObject (hdc, hPen) ; 
MoveTo (hDdC, 0, 0) ; 
LineTo (hDC, Poardert right - rBorder.left - 2,0); 
LineTo (hDC, rBorder.right - rBorder.left - 2, 

rBorder.bottom - rBorder.top - 2) ; 
LineTo (hDdC, 0, rBorder. bottom - rBorder. top - 2); 
LineTo Choc, 0, 0) ; ; 
MoveTo ChbdCc, 0, 15) ; 
LineTo C(hDC, sbcrdec. nicht - rBorder. Left, 15); 
SetBkMode ChDC, Potala ae , 
TextOut Choc, 1, 1, “Custom Frame" - 12); 

DeleteObject. ade : ! 
ReleaseDC ChPopup, hDC) ; 
return COL) > 
case WM_PAINT: , /* bypass client area painting */ 

GetClientRect ChPopup, CLPRECT) &rClient) ; 
ValidateRect ChPopup, (CLPRECT) &rClient) ; 
return COL) ; 


case WM_USER: /* mesgage from parent -— just beep */ 
MessageBeep (0) ; 
break ; : 
case WM_DESTROY: /* stop the popup window */ 
Eaten nee (0) ; 
break ; 
case WM _NCACTIVATE: /* falls through to DefWindowProc() */ 
PostMessage ChPopup, WM_NCPAINT, 0, OL) ; 
default: /* default windows message processing */ 
return DefWindowProc (hPopup, iMessage, wParam, lParam) ; 
} . ‘ 
return (OL) ; 
5 
GETWINDOWEXT | -mWin2.0 mWin3.0- mWin3.1 
Purpose Used with GetViewportExt() to determine the scale the device context. 
_ Syntax DWORD GetWindowExt(HDC hDC); eS Bs 
| Description The MM_ISOTROPIC and MM_ANISOTROPIC mapping modes allow the logical coordinate sys- 
tem of a device context to be scaled to any arbitrary ratio to the physical device. GetViewportExt() 
and GetWindowExt() are used together to determine the current scaling. The scaling factor is 
the ratio of the viewport extent divided by the window extent. For example, if the viewport X 
extent is three and the window X extent is one, the logical coordinate system expands all hori- 
zontal dimensions by a factor of three. If the signs of the viewport and window extents match, the 
coordinate orientation is unchanged. If one of the signs is negative and the other positive, the 
orientation is reversed. This is commonly used to make the Y values increase upward, rather than 
the default system where Y values increase downward. 
Uses Used with windows created with the CS_OWNDC class style, that maintain a private copy of their 
_ device context. 
Returns DWORD, the window extent. The low- order word contains the X value. The high-order word con: 
. tains the Y value. 
See Also GetViewportExtO, SetWindowExt(), SetMapMode OF SetWindow0rg() . 
Parameters 
~hDC HDC: The device context handle. 
Example . See the example under the GetViewportExt() function description. 
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“ 


7 


GetWinpowOrc ~ : : i mWin20 mWin30 mWin3l 


Syntax | 


Description 


Uses 
Returns 
‘See Also 


Parameters 
“ADC ™ 


Example 


GRAYSTRING 
-Purpose~ 
Syntax 


Uses 
Returns 
See Also 


Parameters 
hDC 
hBrush 


lpOutputFune 


Used with GetViewportOrg() to deve the location of the origin of the logical coordinate 
system of a device context. 
DWORD GetWindowOrg(HDC hDC); 


Windows allows two offsets to be applied to the origin (0,0 location) of the logical coordinate 
system. SetWindowOrg() sets up the first offset, called the “window origin.” SetViewportOrg() 


_ sets up the second offset, called the “viewport origin.” The viewport origin is relative to the win- 
_ dow origin, so you can think of the viewport origin as an offset from another offset. 


Used with windows that maintain their own private device context. 


DWORD. The low-order word contains the X offset. The high- order word contains the Y offset. 


GetViewportOrg(), SetViewportOrg(), SetWindowOrg(), SetMapMode(), SetViewportExt(), 
SetWindowExt() 


HDC: The device context Handle. 
See the example under the GetViewportOrg() function description. 


. eWin2.0 mWin3.0 wm Wind. 
Draws grayed text or a grayed bitmap at the given location. 
BOOL GrayString(HDC hDC, HBRUSH hBrush, FARPROC lpOutputFunc, DWORD lpData, int © 
nCount, int X, int Y, int nWidth, int nHeight); 


The graying is accomplished by combining the selected brush and the text string or bitmap. For 
black text characters, this has the effect of eliminating pixels where the brush bitmap is white 
and changing the.remaining pixels to the brush color. This function is a naldover am the 2. 0 


version of Windows, which used this technique to gray menu items. 


Can be used to provide different degrees of “graying” of a string or to gray a bitmap. 
BOOL. TRUE is the function was successful, FALSE on error. 


GetStockObject(). SetTextColor() can be used to paint characters with a gray color, but without 
the elimination of selected pixels. 


HDC: The discs context handle, 


HBRUSH: A handle to the brush to use for graying. Normally, GetStockObject() is used to retrieve 


_ one of the three stock gray brushes (see the following example). . 
~ FARPROC: NULL if TextOut() is to be used for output. lpOutputFunc can also be the procedure- 


instance address of a special output function that you add as part of the program. Use 
MakeProcInstance() to create a gi ocedure-instance address for the function. The function for- 


_ mat is shown below. 


DWORD: If lpOutputFunc is NULL, IpData | is a pointer to the character string to be output. 
Otherwise, /pData is a long pointer to the data to be passed to the output function described 
below. 


int: The amount of data to be output. If nCount i is . NULL, lpData is assumed to be a null-termi- 
nated character string. 


int: The logical X position to start output. 
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Y i 
nWidth 


nHeight 


int: The logical Y position to start output. 


int: The width of the output rectangle | in logical units. Set to NULL if lpData points toa character 
string. 


int: The height of the output rectangle in logical units. Set to NULL if ee points to.a aan 
acter string. 


Custom Output Function 


Example 


The program can provide its own specialized a function. The Se must have the follow- 


_ ing format: 


BOOL FAR PASCAL OutputF'unc (HDC hDC, DWORD sobiala: int ey 

Where: 

hDC is amemory device context containing a bitmap nWidth wide and nHeight tall. The output 
function writes to this device context. 

lpData is the pointer to the data passed by Gee. 
nCount is the number of data bytes passed by GrayString(). 
Like all callback functions, the output function must be de- 
clared in the EXPORTS section of the program’s. .DEF defini- 
tion file. The output function should return nonzero on .. 


success, zero on error. The MM_TEXT mapping mode must be 
in effect prior to calling GrayString(). 


This example outputs the same text with four different levels © 
of graying. The image on a VGA screen is significantly better Figure 10-17. GrayString() 


[— [generic im [~ [=. 
pen gat 


ene aL grass 
This string ta be grayed. 
This string to be grayed. 


.. than that of the illustration in Figure 10-17, as the graying logic Example. 


changes both the bitmap and the gray color used to display the 
letters. Only the bitmap effects are visible in this black and white illustration. 
Note that the last text string is created using TextOut(), so no graying of the text occurs. 


long FAR PASCAL WndProc CHWND hwnd, unsigned iMessage, WORD wParam, LONG LParam) 


{ 
HDC hdc ; 
HBRUSH hBrush ; 7 
char cBuf CJ = {"This string to be grayed."} ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) : 
{ 
- case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
hBrush = ecestovkopyect CLTGRAY_BRUSH) ; 
GrayString (hDC, hBrush, NULL, (DWORD)C(LPSTR) cBuf, 
NULL, 10, 10, NULL, NULL) ; 
hBrush = GetStockObject (GRAY_BRUSH) ; 
GrayString ChDC, hBrush, NULL, (DWORD) CLPSTR) cBuf, 
NULL, 10, 30, NULL, NULL) ; 
hBrush = GetStockObject (DKGRAY. RUSH 
GrayString (hDC, hBrush, NULL, CDWORD)C(LPSTR) cBuf, 
NULL, 10, 50, NULL, NULL) ; 
TextOut ChDC, 10, 70, cBuf, tstrlen (cBuf)) ; 
a ; ReleaseDC (hWnd, hDC) ; 
: -break ; 
[Other program lines] 


407 


WINDOWS API BIBLE 


LPTroDP 
‘Purpose 
Syntax. . 
Description 


Uses 


Returns 
_ See Also 


Example 


long FAR PASCAL WndProc CHWND hwnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ae 


NDC 
POINT 


switch CiMessage) 
3 


wWin2.0 mWin30 mWin3l 
Converts a point from logical coordinates to device coordinates. os 
BOOL LPtoDP(HDC DC, LPPOINT [pPoints, int nCount); 


One or more points i in an ay pointed to by ipPoints can be converted in one call to this fune- 
tion. 


Used with the alternate mapping modes when there is a need to relate a point in the client area 
to an external element such as the mouse position. 


BOOL. TRUE if all points were converted, FALSE on error. | 
DPtoLP(), SetMapModeQ() 


HDC: The device context handle. . 
LPPOINT: A pointer to a point, or the first element in an array of POINT structures. 
int: The number of points to convert. 


The scaling ofa device context determines the difference between device coordinates and logical 
coordinates. The following formulas relate device points (DP) and logical ees (LP): 


DP = Scale * (LP - WindOrg) + ViewOrg ; . 
LP = (1/Scale) * @P - ViewOrg) + WindOrg ; 
Where: 

Scale = ViewportExtent / WindowExtent ; 


This example sets an alternative mapping mode, MM _LOMETRIC. The cursor arrow is moved to 
the origin of the logical coordinates. This example requires two transformations: LPtoDP() to 
convert from the logical coordinates to the device coordinates and ClientToScreen() to convert 
from the device coordinates to the screen coordinates used in positioning the mouse cursor. The 


. cursor moves to the upper left corner of the client areas as changing the mapping mode does not 


automatically change the origin. 


/ 


hOC ; 
perotne 2 


a process windows messages */ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) Pak 
C 58 Sars 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hOC = GetDC ChWnd) ; 
SetMapMode (hDC, MM,  LOMETRIC) ; 
ptPoint.x = ptPoint.y = 0 ; 
_ LPtoDP ChOC, &ptPoint,. 1) ; 
‘ClientToScreen ChWnd, @ptroint) = 
' SetCursorPos (ptPoint. x, pePoint y); 
ReleaseDC (hWnd, hdc) - 


break ; 
[Other program lines] 
OrrserViewrortORG wWin2.0 mWin3. 0 a Win 3.1 
Purpose Changes the X,Y offset of the Togical coordinate system origin. 


Syntax 


DWORD OffsetViewportOrg(HDC 2DC, int X, int ¥); 
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Description 


units in both the X and Y directions using SetWindowOrg(). 
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SetViewportOrg() is used to establish the offset in both the X and Y directions of the origin of the 


logical coordinate system. OffsetViewportOrg() allows the offset to be changed by increments. _ 
Calling OffsetViewportOrg() is equivalent to calling SetViewportOrg() withX and Y values equal © 
to the old values plus the offsets. 


Used with windows that have their own private dieviee: Gites Offsetting the origin can be a 
convenient way to scroll a graphics image. 


DWORD, the previous viewport offset. The low-order word contains the X coordinate otieet: The 
high-order word contains the Y coordinate offset. 


The function descriptions for SetViewportOrg() and Seer) contain more complete 


descriptions of offsets. 


HDC: The device context handle. 
int: The number of device units (pixels) to add to the horizontal offset. 


. int: The number of device units (pixels) to add to the verticai offset. 


This example creates a window with its own private device context. When the program starts or is 
resized (WM_SIZE message received), the mapping mode is set to MM_ISOTROPIC and the ver- 
tical scale expanded by a factor of two. The vertical scale is reversed (negative Y value with 
SetViewportExt()), so that increasing Y values point upward on the windows client area. The © 
viewport origin is set equal to the bottom left corner of the screen using pallets This 
offset is in turn affected by offsetting the window origin by 10 ——— om 


The result of these transformations is that the logical 0,0 point 
on the screen is 10 pixels to the right and 20 pixels above the 
bottom left corner of the window’s client area. 

When the user clicks the “Do It!” menu item, the windowX 
offset is eliminated (10 added to the old offset of -10). The Figure 10-18. ee 
viewport origin is also offset by five in both the X and Y di- portOrg() and OffsetWindow- 
rections. The combined effect of these two offsets shifts the Org() Example. 
origin to the right 15 pixels and down 5. Repeatedly clicking 
the “Do It!” menu item will continue to shift the image to the left and down by 15 pixels horizon- 
tally and 5 pixels vertically. The origin is reset if the window is sized. ~ 

The WinMain() function includes the CS_OWNDC class style as part of the window's class 


- definition. This provides the window with its own private device context. 
_ wndclass.style = CS_HREDRAW | CS_VREDRAW | CS_OWNDC ; 


Note in processing the WM_SIZE message that the client area vertical size is passed as the 
high-order word in the Param parameter. This is convenient for setting the viewport origin at 


the bottom of the client area. 


zone FAR PASCAL WndProc CHWND hind, unsigned oeeesaese WORD wParam, LONG praran) 


HDC hoc : 

DWORD dwView0Org, duWindOrg ; 

char cBuf £101°; . 

switch (iMessage) . '* process windows messages */ 
{ 


case WM_SIZE: 
hoc =. GetDdC ChWnd) ; /* owns DC, no need to release */ 
SetMapMode (hDC, MM_ISOTROPIC) ; 
“ SetWindowExt (hDC, 1, 1); 
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SetViewportExt (hDC, 2, -2) ; 
SetWindowOrg ChDC, -10, -10) ; 
; SetViewportorg chDC, 0, HIWORD (lParam)) ; 
break ; 
case WM_ COMMAND: 
switch (wParam) 
{ ‘ : 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
_ HDC = GetDC ChWnd) ; 
OffsetWindowOrg (hDC, 10, O) ; 
OffsetViewportOrg (hDC, 5, 5) ; 
dwViewOrg = GetViewportOrg ChDC) ; 
dwWindOrg = GetWindowOrg ChDC) ; 
TextOut (hDC, 0, 0, "ViewPort Org =", 
.itoa (LOWORD (dwViewOrg), cBuf, 10) ; 
TextOut (hDC, 60, 0, cBuf, lstrlen (cBuf)) ; 
TextOut (hdc, 70, 0, ",", 1) >; 
itoa (HIWORD (CdwViewOrg), cBuf, 10) ; 
TextOut ChDC, 80, 0, cBuf, lstrlen (cBuf)) ; 
TextOut ChDC, 0, 10, "Window Org =", 12) ; 
itoa (LOWORD (dwWindOrg), cBuf, 10) ; 
TextOut (hDC, 60, 10; cBuf, lstrlen (cBuf)) ; 
TextOut (hdc, 70, 10, ",", 1) ; 
itoa C(HIWORD (dwWindOrg), cBuf, 10) ; 
TextOut Choc, se0e 10, cBuf, lstrlen Cenugyscs 


/*-process menu items */ 


14) ; 


a ‘break ; 

[Other program lines] 

OrrsETWINDOWORG eWin20 mWin30) mWin3l 

Purpose Changes the X,Y offset of the logical coordinate system origin. 

Syntax DWORD OffsetWindowOrg(HDC DC, int X, int Y); 

Description SetWindowOrg() is used to establish the offset in both the X and Y directions of the origin of the- 
_ logical coordinate system. OffsetWindowOrg() allows the offset to be changed by increments. 

Calling OffsetWindowOrg() i is equivalent to ae SetWindowOrg() withX and Y values equal to 

. the old values plus the offsets. 

Uses Used with windows that have their own private fievice’ context, Offsetting the: origin can be a 
- convenient way to scroll a graphics i image. 

Returns DWORD, the previous window offset. The low-order word contains the X coordinate offset. The 

high-order word contains the Y coordinate offset: 
See Also The function descriptions for SetWindowOrg() and GetWindowOrg() contain more complete de- 
scriptions of offsets. 
Parameters . 
“ADC HDC: The device context handle. 
Xx int: The number of device units (pixels) to add to the horizontal offset. 
Y int: The number of device units (pixels) to add to the vertical offset. 

Example See the previous example under OffsetViewportOrg(). . 

RELEASEDC mWin20 mWin30 mWin31 

Purpose Frees the device context. 

Syntax int ReleaseDC(HWND hWnd, HDC hDC); ; . 

Description This function is used to free the device context after output is completed. Windows allows a 


maximum of five device contexts to be open at one time, but only one for a given device: Releasing 
the DC is necessary unless the window class was created with the CS_OWNDC style. 
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I — eat 


Uses It is good practice to use ReleaseDC() immediately atter output is completed. Use EndPaint() to 
release the device context retrieved by BeginPaint() in processing a WM_PAINT message. 

Returns . int. Returns nonzero if the device context was released, zero on error. 

See Also GetDC(Q) . 

Parameters 

hWnd HWND: The handle of the window. 

hDC HDC: The device context to be released. This is the value returned by GetDC() before output was 
started. 

Example — This example outputs the string “This is a character string.” when the user hits the “Do It!” menu 


item. The device context is released immediately after use. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


HOC hDC ; 
char ey Cl.= C"This isa character’ string."} ; 
switch CiMessage) /* process windows messages */ ‘ 
case WM_COMMAND: : /* process menu items. */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it” menu item */ 
hDC = GetDC stupa 
TextOut ChDC, 10, eeuty Lstrlen (cBuf)) ; 
ReleaseDC Gin hDC) ; 
break ; 
[Other program lines] 
REMOVEF ONTRESOURCE — mWin2.0 mWin3.0 mWin3.1 
Purpose Removes a font from the system and frees all memory associated with the font. 
Syntax BOOL RemoveF ontResource(LPSTR /pFilename); 
Description Fonts take up memory space. It is good practice to remove custom fonts loaded by an application 


when the application is terminated. Other top-level windows should be notified that the font has 
been removed from the system by sending a WM_FONTCHANGE message. 


Uses ’ Usually used when processing the WM_DESTROY message to remove added font resources. Do 
not remove.the normal Windows system fonts, or any other font that was not loaded by the ap- 
. plication. 
Returns BOOL. TRUE if the font was removed, FALSE on error. 
See Also AddFontResource(), FindResource() 
Parameters é 
lpFilename LPSTR: A far pointer to a null-terminated character string containing the font file name. This - 


should be a complete DOS file name including the directory path and the “.FON” file extension. 
Alternatively, IpFilename can contain a handle to a font resource loaded as part of the resource 
.RC file. The resource file should include a line like 


1 FONT script.fon 


The FindResource() function is then used to obtain the handle to the font. The handle be- 
comes the low-order word of IpFilename. The high-order word must be zero. 


- Related Messages WM_FONTCHANGE should be sent to all top-level windows after a font is loaded or removed. This 
meee _ makes the new font’s availability known to all programs running on the system. 
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Example 


This example shows a font file called “script.fon” being loaded at the start of the program and 
removed at the end. SendMessage() is used to notify all other top-level programs of the font’s 
presence. By setting the first parameter in SendMessage() equal to -1, all top-level windows ate 
ceive the message. 


Long FAR PASCAL WndProc. CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ae 


int 


“nFontLoad ; 


switch (iMessage) , /* process windows messages */ 
{ 


case WM_CREATE: /* bring in the font file */ 
nFontLoad = AddFontResource (C(LPSTR) "script.fon") ; 
if (!nFontLoad) 

MessageBox (hWnd, “Could not load font.", “Warning”, 
MB_ICONHAND | MB_ OK) ; 


else 
SendMessage (-1, WM_FONTCHANGE, 0, OL) : 
break ; tes é 
case WM_COMMAND: /* process menu items */ 
/* other program lines here */ 
break ; 
case WM_DESTROY: /* stop application */ 


RemoveFontResource ((LPSTR) “script. fon") : 
SendMessage (-1, WM L_.FONTCHANGE, 0, OL) ; 
PostauitMessage (0) ; 
break ; : 
default: a hel default windows message processing */ 
' return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; 


} 7 
REsETDC 
Purpose 
Include File 


Syntax 
Description 


Uses 


Returns 
See Also . 


Parameters 
hDC 


lpInitData 


OWin20 OWin3.0. mWin31 
Updates a printer device context. 

<drivinit.h> _ 

HDC ResetDC (HDC hDC, LPDEVMODE neha: 


The printer device context, created by CreateDC(), can be updated at any time using ResetDC(. 
The update is based on data in a DEVMODE data structure, passed to the function. The DEVMODE 


data is typically initialized using ExtDeviceMode(). Changes to the DEVMODE data can include 


any value except the driver name, device name, or output port. 


ResetDC() can be used in the middle of a printing job to change printer settings, such as paper 
orientation or printing resolution. This supersedes a number of Escape() function calls that were 
used to change printer settings under Windows versions 2.0 to 3.0. 


HDC, the original device context handle. Returns NULL on error. 
Seine): ExtDeviceMode(), Bscape(), 


HDC: ‘The handlé to the printer device context. This is the value shared by CreateDCQ). 


LPDEVMODE: A pointer to. a DEVMODE data structure containing the new settings for the 
printer. This data structure typically is initialized using ExtDeviceMode() prior to making 
changes to the data. The DEVMODE data structure is defined in DRIVINIT.H as follows: 


/* size of a device name string i ae 
#define CCHDEVICENAME 32 


typedef struct devi camade f . ok , 
char dmDeviceName[ CCHDEVICENAME]; /* device name string */ 


/ 


WORD dmSpecVersion; /* driver specification ver. eg. 0x300 */ 
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WORD dmDriverVersion; 
WORD dmSize; 

WORD dmDriverExtra; 
DWORD dmFields; 


short dmOrientation; 
short dmPaperSize; 
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/* OEM dirver version number */ 
/* size of DEVMODE structure */ 
/* number of bytes following DEVMODE data */ 

: - /* bit-field for which of the following dm */ 
/* values are supported. Bit 0 is one if */ 
/* dmOrientation is supported, etc. */ 
/* DMORIENT_PORTRAIT or DMORIENT_LANDSCAPE */ 


/* DMPAPER_LETTER, OM_PAPER_LEGAL, DM_PAPER_A4 */ 


/* DMPAPER_CSCHEET, DMPAPER _DSCHEET, DMPAPER_ESHEET, DMPAPER_ENV_9 */ 
/* DMPAPER_ENV_10, DMPAPER_ENV_11, DMPAPER_ENV_12, DMPAPER_ENV_14 */ 


short dmPaperLength; 
short dmPaperWidth; 
short dmScale; 

short dmCopies; 

short dmDefaultSource; 
short dmPrintQuality; 


- short dmColor; 
short dmDuplex; 


/* overrides dmPaperSize, in mm/10 */ 

/* overrides dmPaperSize, in mm/10 */ 

/* page is scaled by dmScale/100 */ 

7* number of copies supported */ 

/* Default paper bin */ 

/* DMRES_HIGH, DMRES_MEDIUM, DMRES~ LOW, */ 
/* or DMRES_DRAFT */_ 

/* DMCOLOR_COLOR or DMCOLOR_MONOCHROME */ 
/* DMDUP_SIMPLEX, DMDUP_HORIZONTAL, */ 


/* or DMDUP_VERTICAL */ 


BYTE dmDriverData CdmDriverExtral ; /* 0 or more bytes of extra data */ 


} DEVMODE; 


typedef DEVMODE * PDEVMODE, NEAR * NPDEVMODE, FAR * LPDEVMODE; 


‘Related Messages WM_DEVMODECHANGE 


Example This example illustrates several advanced techniques in dealing with a printer device driver. 
When the user clicks the “Do It!” menu item, WIN.INI is parsed to obtain the driver name and 
output port name. The driver is then loaded, and the address of the driver's ExtDeviceMode() 
function is determined. ExtDeviceMode() is called three times. The first call determines the size 
of the memory block needed to contain the driver's DEVMODE data structure. A global memory 
block of this size is then allocated. The second call to ExtDeviceMode(), with the DM_COPY flag 
set, copies the device data to the global memory block. The third call to ExtDeviceMode(), with 
the DM_PROMPT flag set, executes the driver's setup dialog box. If the user does not click the 
cancel button within the dialog box, the WM_DEVMODECHANGE message is sent to all running © 
applications to alert them that the printer settings may have been altered. 

Next, the program outputs two lines of text to the printer. The first is output in the printer's 
default paper orientation mode, assumed to be portrait. ResetDC() is then called to change the 
printer device. context to landscape mode. The second line of text is then output. ResetDC() is 
called a final time to return the printer to portrait mode. Note that error checking on the memory 
allocation functions was omitted in this example for clarity. See the example under the 

_ GlobalAlloc() function description for a more complete example of memory allocation. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam,*LONG lParam) 
{ 


char : ’ szPrinter C64], szSysDir C128], szFullDriver (2561, 
*szDriver, *szDevice, *szOutput ; 
HANDLE hDriver ; 
LPFNDEVMODE ipfnDeviceMode ; 
LPDEVMODE LpDevMode ; 
_ Hobe ~ -hOCPrinter ; 
~~ int ‘nReturned, nBytes ; 
‘HANDLE hMem >; : z 


switch CiMessage) /* process windows messages */ 
case WM_COMMAND: 
switch (wParam) 
{ 
case IDM_DOIT: - /* get driver name from WIN.INI */ 
GetProfileString ("“windows", “device”, "", 
szPrinter, 64) ; 


/* process menu items */ 
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szDevice 


-szDriver 


szOutput 


GetSyste 


lstrepy 


lstrcat 
lstrcat 
lstrcat 


 hDriver = 


strtok (szPrinter, ",") ; 
strtok (NULL, ",") ; 
strtok (NULL, ",") ; 

/* build full driver path/file spec */ 
mDirectory CszSysDir, 128) ; 
(szFullDriver, szSysDir) ; 
CszFullDriver, "\\") ; 
(szFullDriver, szDriver) ; 
CszFullDriver, “.DRV") ; 

/* get handle to driver */ 
eobde brary (szFullDriver) ; 


uu 


if ChDriver > 31) 


{ 


LpfnDeviceMode = (LPFNDEVMODE) GetProcAddress 
ChDriver, “ExtDeviceMode") ; 
if (lpfnDeviceMode) 
{ /* find size of DEVMODE structure */ 
nBytes = (* LpfnDeviceMode) (hWnd, hDriver, 
LpDevMode, szDevice, szOutput, 
NULL, NULL, NULL) ; 
hMem = GlobalAlloc = 
(GMEM_MOVEABLE ] GMEM_ZEROINIT, nBytes) ; 
LpDevMode = (LPDEVMODE) GlobalLock (hMem) ; 
/* initialize DEVMODE data */ 
(*. UpfnDeviceMode) 
(hWnd, hDriver, LpDevMode, 
szDevice, szOutput, NULL, NULL, DM_COPY) ; 
‘/7* call printer dialog box */ 
nReturned = (* LpfnDeviceMode) (hWnd, hDriver, 
lpDevMode, szDevice, Sz0Ur Rue y NULL, 
ee NULL, DM_PROMPT) ; 
if (nReturned != IDCANCEL) 
‘PostMessage (-1, WM_DEVMODECHANGE, 0, 
(DWORD) (LPSTR) szDevice) ; 


hDCPrinter = CreateDC (szDriver, szDevice, 
szOutput, CLPSTR) LpDevMode) ; 
; /* output in default mode ef 
Escape (hDCPrinter, STARTDOC, 4, "Test", NULL) ; 
TextOut (hDCPrinter, 10, 10, 
“Text Output Appears Portrait Mode.", 34) 3 


’ Escape ChDCPrinter, NEWFRAME, NULL, NULL, NULL) ; 


else 


Escape (hocPrinter, ENDDOC, NULL, NULL, NULL) ; 
/* switch printer to tendscape. */ 
LpDevMode->dmOrientation = DMORIENT_LANDSCAPE ; 
if (ResetDC ChbCPrinter, LpbewMode)) 
{ 
/* output in ladecane mode */ 
Escape chDcPrinter, STARTDOC, 5, "Test2", 
NULL) ; 
TextOut (hDCPrinter, 10, 10, 
Text Output Appears Landscape Mode.",, 
35) ; 
Eecere ChDCPrinter, AEWFRAME, 
NULL, NULL, NULL) ; 


Lpbeviade-=dugrientation = 
: DMORIENT_PORTRAIT.; 
ResetDC (hDCPrinter, LpDevMode) ; 


else 
MessageBox (hWnd, 
“Could not change printer BGs 
“Message”, MB. OK) ; 
GlobalUnlock cnnlen? 7 ; 
GlobalFree (hMem) ; 
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~ 


MessageBox (hWnd, "Could not load driver file.", 
“Message”, MB_OK) ; 
break ; ; 
case IDM_QUIT:. 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DEVMODECHANGE: 
MessageBox ChWnd, 
"Notification that printer settings were altered.", 
- CLPSTR) lParam, MB_OK) ; 
break ; 
case WM_DESTROY: 
PostQuitMessage (0) ; 
break ; 
default: 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} : : 
return (OL) ; 


RESTOREDC | mWin2.0 mWin30 mWin31 
‘Purpose Restores ‘an old device context saved with SaveDC(). 


: . : [= generic an 
Syntax BOOL RestoreDC(HDC hDC, int nSavedDC); : 


Description The current device context can be saved at any time with mnie with new DC ote 
SaveDC(). Each call to SaveDC() places a copy of the current Roe re ee nee 
device context settings in a stack, above the last saved DC. is oe 


Calling RestoreDC() returns the device context to the state Figure 10-19. RestoreDC() | 
. when it was saved. If more than one device context is saved Example. 
Hog before RestoreDC() is called, the RestoreDC() calls are nor-. 
mally done in the reverse order to the order of the SaveDC() calls. Ifa DC below the last saved DC 
is restored, the ones above it in the stack are destroyed, as shown in Figure 10-19. ' 


Uses , Handy if you are changing pen colors, fonts, etc. within a graphics intensive part of the program. 
Avoids having to continually reload old pens, fonts, etc. to keep the device context current. 

Returns BOOL. TRUE if the device context was restored, FALSE on. error. 

See Also SaveDC(), GetDC(); BeginPaint() 

Parameters 7 | 

hDC _ HDC: The device context handle. 

nSavedDC int: The value returned by SaveDC() when the device context was saved. Set to —1 to return the 
most recently saved DC. 

Related Messages WM_PAINT 

Example This example saves the device context before changing to a new font. After the font is used, the 


old device context is restored to output the bottom line using the system font. 


Pf 5 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ; 


HDC hoc ; 
HFONT hFont ; 
int nOLdDC ; 
switch (iMessage) _/* process windows messages */ 
{ ; : 
case WM_COMMAND: /* process menu items */ 

switch (wParam) 

{ 

case IDM_DOIT: /* User hit the "Do it" menu item */ 
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hDC = GetDC ChWnd) ; 
nOldDC = SaveDC ChDC) ; 

' hFont = CreateFont (18, 0, 0, 0, 400, 0, 0, 0, 
OEM_CHARSET, . OUT_DEFAULT_PRECIS, 
CLIP_DEFAULT_PRECIS, DEFAULT_QUALITY, 

. DEFAULT_PITCH | FE ROMAN, “roman") ; 
SelectObject (hDC, hFont) ; 
TextOut (hDC,.10, 40, 
“Output with new oe seveingext ", 28) ; 
RestoreDC ChDC, nOldDC) ; 
TextOut ChDC, 10, 40, 


“Output with old DC settings.", 28) ; - 
: ReleaseDC ChWnd, hDC) ; 
a break ; 
[Other program lines] 
SaveEDC | mWin2.0 mWins0 mWin3.1 
Purpose Saves a device context for future use. , . 
Syntax int SaveDC(HDC ADC); — 
Description, The current device context can be saved at any time with SaveDC(). Each call to SaveDC() places 
zo a copy of the current device context settings in a stack, above the last saved DC. Calling 
RestoreDC() returns the device context to the state when it was saved. The saved DC will be 
; removed from memory when the program terminates. 
— 
Uses Handy if you are changing pen colors, fonts, etc. within a graphics iicnaive part of the program. 
Avoids having to continually reload old pens, fonts, etc. to keep the device context current. 
Returns int, the number of the saved device context. Zero on error. . . 
See Also RestoreDC(), ReleaseDC(), EndPaint() 
Parameters . 
hDC HDC: The device context handle. : 
Related Messages WM_PAINT 
Example See the previous example under RestoreDC(). 
ScateViewrortEXtT mWin2.0 mWin3. 0. m Win 3.1 
Purpose Changes the scale of the logical coonfinate system for a device context. 
Syntax . DWORD ScaleViewportExt(HDC hDC, int Xnum, int Xdenom, int Ynum, int Ydenom), 
Description The existing viewport xtents (scaling) is a ratio based on the following formulas to come up with 
the new scaling: . 
xNewVE = (xOIdVE * ban) /Xdenom ; 
yNewVE = (yOldVE * Ynum) / Ydenom ; 
Uses | This is a convenient way to change the scaling of the a coordinate system. Only the 
| MM_ISOTOPIC and MM_ANISOTROPIC mapping modes can be scaled. N 
Returns The:previous viewport extents (scaling). The coy ornes word contains the X mes while the 
high-order word contains the Y value. 
See Also ScaleWindowExt(), SetMapMode(), GetViewportExt(), SetViewportExt() 
Parameters a 
hDC HDC: The device context handle. 
Xnum 


int: The multiplier for the current X extent. 
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Xdenom int; The divisor for the current X extent. 

Ynum int: The multiplier for the current Y extent. 

Ydenom int: The divisor for the current Y extent. 

Example In the example shown in Figure 10-20, three circles, 20 logical units 


in diameter, are drawn at the logical coordinates 40,40. The three 

circles end up in different places, and different sizes, due to the 

scaling of the logical coordinates. To begin, the MM_ISOTROPIC 

mapping mode is set up with one logical unit equal to one device 

unit (pixel) in both the X and Y direction. Because the origin is not 

changed, the default origin at the upper left corner remains in effect. 

Circle 1 is drawn at 40,40 and ends up being 20 pixels in diameter. 
Before circle 2 is drawn, both the X and Y extents are scaled up 

by a factor of two. This results in circle two being drawn twice asfar Figure 10-20. 

away from the origin, and twice as big (measured in pixels). For _ScaleViewportExt() and 

circle 3, the scaling is returned to one logical unit equals one pixel, © ScaleWindowExt() 

but the origin is relocated to the lower right corner. The Y axis is also Examples. 

inverted, so that increasing Y values refer to higher positions on the 

client area. These changes result in circle 3 being drawn at location 40,40 relative to the bottom 

left corner, instead of relative to the top left corner. 


é 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 4 : 
HDC hDC ; 


RECT rClient >; — = 
switch (CiMessage) /* process windows messages */ 
{ 

tase WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
SelectObject (hDC, ‘setstockobject CBLACK_PEN)) ; 
as . SetBkMode (hDC, TRANSPARENT) ; 
SetMapMode (hDC, MM_ ISOTROPIC) ; 
SetWindowExt (hDC, 1, 1) ; ; 
/* first create a map aide where Logical unit = pixel */ 
SetViewportExt ChDC, 1, 1) ; 
Ellipse (hDC, 40, 40, 60, 60) ; 
TextOut (hDC, 40, 40, "1", 1) ; 
/* now create a map mode where logical unit = 2 pixels */ 
/* map mode = 2 * default */ 
ScaleViewportExt ChDC, 2, 1, 2, 1) ; 
Ellipse (hDC, 40, 40, 60, 60) 
TextOut (hDC, 40, 40, "2", 1) 
/* undo the last scaling */ 
ScaleViewportExt (hDC, 1, 2, 1, 2) ; 
/* now create a map mode where the origin is at the */ 
/* lower left corner, and Y values increase upwards. */ 
ScaleWindowExt (hDC, 1, 1, 1, -1) ; 
GetClientRect (hWnd, (LPRECT) &rClient) ; 
SetViewportOrg (hDC, rClient.left, rClient.bottom) ; 
Ellipse ¢ChdC, 40, 40, 60, 60) ; 
TextOut ChDdC, 40, 40, "3", 1) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 


[Other program lines] | \ 


We Ne 
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ScateWinpowE xt , me Win2.0 mWin3.0 mWin31 
Purpose.” Changes the scale of the logical coordinate system for a device context. 

Syntax~ ne DWORD ScaleWindowExt(HDC DC, int Xnum, int Xdenom, int Ynum, int Ydenom); 
Description The existing window extents (scaling) is a ratio based on the following formulas to come up with 

: ____ the new scaling: : 

© Seed xNewWE = (xOldWE * Xnum) /Xdenom ; 

/ f° YNewWE = (yOldWE * Yum) / Ydenom ; 

Uses vee . This is a convenient way to change the scaling of a coordinate system. Only the MM_ISOTOPIC — 
: *"» and MM_ANISOTROPIC mapping modes can be scaled. . 
Returns “The previous window extents (scaling). The low-order word contains the X value, while the high- 


., ..order word contains the Y value. 


See Also \ — SetMapMode(), sev adawiet, SetWindowExt() _ 

Patdmeters “ : ee en este 

OCA "He: The vide context handle, ae ee ae 

_Xnum een The. ‘multiplier: for the current X extent, ee ies 

Adenoma: «2 yyixsjcint: The, divisor for: the current X extents: ay Rie ide a ye 

Ynum int: The multiplier for the’éurrent Y extent.: “00° Ss beer rvs te 

Ydenom int: The divisor for the current Yextent. ee Cr eee 

Example ‘The the previous exaniple under ScaleViewportExt(). ean eas 

SETBKCOLOR ie Pe 5 Set Loramie @ Win 2.0... Win3.0., @ Win 3.1 

| Purpose Sets the olor of the background surrounding each charge dashed line, or hatched brush. 

Syntax DWORD SetBkColor(HDC hDC, DWORD erColor);:*' 

Description The background color is used to-fill in the spaces around chavislene dashed lines, and between 
__ the lines of hatched brushes. The: default background | color is white. SetBkColor() allows you to 

: *‘ Change the background color: used. ‘by the device, context. . 

Uses Necessary when text, lineS‘or ‘brushes are painted against a color other than white. 

Returns. « : ; « The previous background color. as an RGB color value: Returns 0x80000000 on error. See Chapter 
11, Painting the Screen, for: a discussion. of the’ RGB color model. | 

See Also — _peearetodeO), CreatellatehBrush(), CreatePen(); TextOut(), GetBkColor(), GetBkMode() 

Parameters **' * ee ne 

hDC HDC: The dpvits context handle” ; 

crColor DWORD: A rae nm olor value. Use the RGBO macro as create a new color i ue. 


Related Messages WM _PAINT.’ ee Ss ce ORAS ee tea 


Example ** nay “* 2 This progiam fragment: demonstrates output of a character string with a fixed color background. 
oy “Tn this case, ‘the text i is s magenta and the background i is green (an awful color combination!). 


Long FAR PASCAL. WndProc: CHUND, hwnd, Sineigned iNessase,, WORD wParam, LONG lParam) 


ies Beg st a 
oS yee oe 


HDC hoc ; >: ae. 
char : cBuf CI = CoThiasis@ character string. "> ; 
switch (CiMessage) /* process windows messages. */ one oacat 
{ , on TAPE Res 
case WM_COMMAND: '/* process menu items */ 
“ “N 
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switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
SetBkMode (hDC, OPAQUE) ;. 
SetBkColor (hDC, RGB (0, 255, 0)) >; 
SetTextColor ChDC, RGB (255, 0, 255)) ; 
TextOut (hDC, 10, 10, cBuf, strlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) > 


break ; 
[Other program lines] 
SETBKMopE BWin20 mWin3.0 mWin3.l 
Purpose Changes the background painting mode. ; 
Syntax int SetBkMode(HDC ADC, int nBkMode); 
Description | Sets the background painting mode. OPAQUE means that the spaces around the characters, 


dashed lines, and hatched brushes will be filled in with the background color. Selecting a TRANS- 
PARENT mode keeps the rectangular area around each character from “blocking out” the back- 


_. ground. 
Uses Frequently used to make the new text “blot out” the old text. 
Returns int, the previous background mode. 
See Also SetBkColor(), TextOut(), GetBkColor(), GetBkMode() 
Parameters . 
hDC HDC: The device context handle. 
nBkMode int: The background painting mode. It can be either OPAQUE or TRANSPARENT. 
Related Messages WM_PAINT 
Example See the previous example with SetBkColor(). 
SeTMarpMope _ . me Win2.0 mWin30 Wind) 
Purpose Changes the mapping mode for a device context. 
Syntax int SetMapMode(HDC DC, int nMapMode); 
Description When a device context is first created, it uses the default set of units for measuring locations on 


the client area. The default units are in pixels, measured from the top left corner of the screen. 
These units are used to locate characters and graphics for functions like TextOut() and LineTo(). 

The alternate mapping modes allow you to use inches or millimeteres to measure locations. 
These are not exact sizes, as Windows does not know the precise size of the equipment being 
used: These modes will provide much more consistent sizing in converting between devices than 
if the default MM_TEXT mapping mode is used. Two of the mapping modes allow the creation of 
custom systems of units. These mapping:‘modes are typically used to scale graphics to fit a de- 
fined area without having to recalculate the positions of each location. 


Uses The inch and millimeter mapping modes assure you that the output will continue to be reason- 
ably sized on different video and printer systems. 


Returns int, the previous mapping mode. 


See Also SetWindowExt(), SetViewportExt(), SetViewportOrg() 
Parameters ES ia 

hDC HDC: The device context handle. 

nMapMode int: One of the mapping modes in Table-10-13. 
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Meaning - 


MM _. ANISOTROPIC This is the most flexible system of units. Either axis can have any eins factor. Use SetWindowext ' and 
SetViewportExt(} to set the scaling. 


- MM_HIENGLISH Each logical unit is 0.001 inch. X increases to the right. Y increases upward. 
MM: HIMETRIC Each logical unit is 0.01 millimeter. X increases to the right. Y increases upward. 


E MM_ISOTROPIC Arbitrary scaling of the axes, but the X and Y scaling must be the same. Use SetWindowEt and 
SetViewportExt() to set the orientation and scaling. 


MM_LOENGLISH — Each logical unit is 0.01 inch. X increases to the right. Y increases upward. 
; _MM_LOMETRIC Each logical unit is 0.1 millimeter. X increases to the right. Y increases upward. 


MM_TEXT This is the default mapping mode. Each unit equals one pixel. X increases to the right. Y increases 
. _ downward. 
MM_TWIPS Each logical unit is 1/20 point, or 1/1440 of an inch. X increases to the right. Y increases upward. 


Table 10-18. Device Context Mapping Modes. 


_ Example The example shown in Figure 10-21 shows how to change both - ea wae — “agnenic 2a 8r5 pe 
E the mapping mode and the viewport origin. When the device 
context is created, it has the default MM_TEXT mapping mode. 
0,0 is in the upper left corner. Following the first text output, 
- the mapping mode is switched to MM_LOMETRIC and the ori- 
gin moved to 50,50. The MM_LOMETRIC system has Y values Figure 10-21. SetMapMode( ) 
increasing upward, so the 100,100 location is above and tothe Example. . 
‘right of the new origin. 


100,100 MM_LOMETRIC 


0,0 MM_LOMETRIC 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
C 


HDC hoc ; 
switch CiMessage) /* process windows messages */ 
: ‘ 
case WM_COMMAND: , /* process menu items */ 
switch (wParam) 
{ j 
case IDM_DOIT: /* User hit the "Do it” menu item */ 
hDC = GetDC ChWnd) ; 
TextOut C(hDC, 0, 0, "0,0 MM_TEXT", 11) ; 
SetMapMode (hDC, MM_LOMETRIC) ; o 
SetViewportOrg (hDC, 50, 50) ; 
TextOut ChDC, 0, 0, "0,0 MM_LOMETRIC", 15) ; 
TextOut (hDC, 100, 100, "100, 100 MM_LOMETRIC", 19) ; 
ReleaseDC ChWnd, hDC) ; 
: break ; 
[Other program lines ] 
SETMAPPERF LAGS mWin2.0 mWin30 mWin3l 
Purpose =~ —~——« Adjusts the way CreateFont() and CreateFontIndirect() adjust for font dimensions outside of 
; those specified in the font data: _ 
Syntax DWORD SetMapperFlags(HDC hDC, DWORD dwFlag); 
Description © CreateFont() and CreateFontindirect() will normally interpolate to achieve specified font sizes 


and aspect ratios not described in the font data. Use SetMapperFlags() to force the use of the 
nearest matching font or to allow interpolation. 


Returns The previous mapper flag value; 1 for exact matching, 0 if interpolation was allowed. 
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See Also 


Parameters 
hDC 


dwFlag 


Example 


10. DEVICE CONTEXTS, TEXT OUTPUT, AND PRINTING V 


CreateFont(), CreateFontIndirect() 


HDC: The device context handle. 


DWORD: If the low-order bit is 1, exact matching is forced. If the low-order bit is 0, interpolation 
is allowed. 


tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ é. 


HDC 
HFONT 


hOC ; 
hFont ; 


switch CiMessage) /* process windows messages */ 


{ 


[Other program lines] 


case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
SetMapperflags ChbC, OL) ; 
hFont = CreateFont (30, 8, 0, 0, 400, 0, 0, 0, 
OEM_CHARSET, OUT_DEFAULT_PRECIS, 
CLIP_DEFAULT_PRECIS, DEFAULT_QUALITY, 
DEFAULT_PITCH | FF_SWISS, “swiss") ; 
SelectObject (hDC, hFont) ; , 
TextOut ChDC, 10, 10, "Mapper flag not now set.", 24) ; 
SetMapperFlags ChDC, 1L) >; ; 
hFont = CreateFont (30, 8, 0, 0, 400, 0, 0, 0, 
OEM_CHARSET, OUT_DEFAULT_PRECIS, 
CLIP_DEFAULT_PRECIS, DEFAULT_QUALITY, 
DEFAULT_PITCH |] FF_SWISS, “swiss") ; 
SelectObject (hDC, hFont) ; 
TextOut (hDC, 10, 50, "Mapper flag now set to 1", 24) ; 
ReleaseDC (hWnd, hDdC) ; 
DeleteObject (hFont) ; 
break ; 


SETTEXTALIGN w@Win2.0 mWin3.0 - mWin3.1 


Purpose 
Syntax 
. Description 


Uses 
Returns 


See Also 


Parameters 
hDC 


Changes the text alignment for a device context. 
WORD SetTextAlign(HDC hDC, WORD wFlags); 


Both TextOut() and ExtTextOut() specify where the output string should start based on a logical 
X,Y position. By default, the device context uses the upper left corner of the first character as the 
X,Y location. SetTextAlignQ) allows you to change this alignment location to other locations on 
the first character. 

There is also a special flag labeled TA_UPDATECP which allows TextOut() and ExtTextOut() 
to keep track of where the end of the output string ended up on the device context. This allows 
you to use multiple calls to the output functions, with each successive string ending up at the end 
of the last one. 


Frequently used to center text if you use the TA_CENTER style. 

int, the previous text alignment. The low-order word contains the horizontal alignment. The high- 
order word contains the vertical alignment. 

TextOut(), ExtTextOut(), GetTextAlign() 


HDC: The device context handle. / 
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wFlags WORD: One or more of the flags listed in Table 10-14. A vertical, horizontal, and update flag can 
all be combined using the C language binary OR operator (I). 


Meaning 


TA_BASELINE The baseline of the first character is used to specify the string position. 
TA_BOTTOM The bottom of the first character is used to specify the string position. 


TA_CENTER The center of the first character is used to specify the string position. 
TA_LEFT The left side of the first character is used to specify the string position. 
TA_NOUPDATECP The location at the end of the last text output is not saved. 

TA_RIGHT The right side of the first character is used to specify the string position. 
TA_TOP The top of the first character is used to specify the string position. 


TA_UPDATECP _ The position at the end of the last text output is saved. The next call to TextOut( ) or ExtTextOut( ) will start 
from this location, ignoring the X, Y data in the output function parameters. 


Table 10-14. SetTextAlign() Flags. 


Note The default values for a device context are TA_LEFT, TA_TOP, and TA_NOUPDATECP. 


Example The example shown in Figure 10-22 demonstrates several uses _ 

of SetTextAlign(). The character strings “Top” and “Bottom” ee ~generic Pe fy fa 
are both output with a vertical position (Y) value of 50. The 
second string ends up above the first as the text alignment is Second Line In Two Parts 
changed so that the Y value refers to the bottom of the charac- 2 
ter, instead of the top. The character string “Second Line In Bottom 
Two Parts” is output using two calls to TextOut(). As the text Top 

-alignment is set to TA_UPDATECP before calling TextOut(), 
the character position data is ignored. Each character location Figure 10-22. SetTentAtign( - 
follows the end of the last call to TextOut(). Examples. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC = DC | ‘. 
switch (iMessage) /* process windows messages */ 
case WM_COMMAND: ; /* process menu items 7 ae 
switch (wParam) 
{ , 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
SetTextAlign (hDC, TA_TOP) ; 
TextOut (hDC, 10, 50, "Top", 3) ; 
SetTextAlign (hDC, TA_BOTTOM) ; 
TextOut ChDC, 60, 50, Bottom", 6) ; 
SetTextAlign hdc, TA_TOP | TA —UPDATECP) ; 
TextOut (hDC, 10, 0, ' "Second Line", 11) ; 
TextOut C(hDC, 0, 0, “In Two Parts", 13) , 
ReleaseDC (hWnd, hDC) ; 
break ; 
[Other program lines] 
SETTEXTCHARACTEREXTRA mWin2.0 mWin3.0 mWin3l 
Purpose Adds additional space between characters of a device context. 
Syntax int SetTextCharacterExtra(HDC ADC, int nCharExira); 
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~ Description 


Uses 
Returns 


See Also 


Parameters 
ADC 


nCharExtra 


Example 


10. DEVICE CONTEXTS, TEXT OUTPUT, AND. PRINTING. ¥ 


This function allows you to add extra space between 
the letters of the currently selected font of a device 
context. The extra space is added between the 
characters output by TextOut() and ExtTextOut(). 
There is no way to reduce character spacing below 
the amount specified in the font description. 


«3 genetic” 2.3 


oe vet 
5 « Je 
Sas gts we egal eos i cae 


j This is normal spacing. 
Extra Spaces. 


Figure 10-23. 


Handy for making text “fit” in predefined areas. , 
SetTextCharacterExtra{) Example. 


dnt, the previous extra character spacing (usually 
zero). , 


GetTextCharacterExtra(), SetMapMode(), TextOut(), ExtTextOut() 


HDC: The device context handle. ee et 


int: The number of extra logical units of space to add between characters. For: the default 
MM_TEXT mode, this is the extra number of pixels. For the other mapping modes, the extra 
logical units are rounded to the nearest pixel. 


Figure 10-23 shows the effect of adding extra spaces between characters. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned Meseagey, WORD wParam, LONG lParam) 
{ 


HOC 


switch (iMessage) 


hdc ; 


eet | 


/* process windows“messages */ 


case WM_COMMAND: 
switch (wParam) 


/* process menu items */ ~-' ° 


case IDM_DOIT: /* User hit the "Do it” menu item */ 
hDC = GetDC (hWnd) ; 
TextOut ChDC, 10, 10, "This is normal spacing.", 23) ; 
_SetTextCharacterExtra (hDC, 10) ; 


TextOut (hDC, 10, 30, "Extra Spaces.", 13) pos sei hay 
ReleaseDC ChWnd, hDC) ; 
break ; Giese «RNa ohne es LH 
[Other program lines] ee eo oe ee ache a 
SETTEXTCOLOR Win2.0° wWin3.0 wm Win'3i1 
Purpose Changes the text color for a device context. a au . re a ee aa 
Syntax DWORD SetTextColor(HDC ADC, DWORD crColor); ae 
Description The default text color for a device context is black. This function alow any RGB color to be set 
for text output with TextOut(), ExtTextOut(), etc..The color stays in effect until the device con-. 
text is released, or another text color is set. See. Chapter li, cds the Screen, for an expla- 
nation of RGB color values. . soe aes oe sa 
Uses Colored text output. | see rae ae a ; 
Returns The 32-bit color value for the previous text color. ee ioe : oct tae 
See Also -GetTextColor(), SetBkColor() 2 MPR a eb oat ele id 
Parameters oh RAS ace ee eee oie bes 
hDC HDC: The device context handle, Jeadre fasucgl bah aval 
crColor - COLORREF: The 32-bit color value for thie. 6 teat ‘This canbe set with. ie RGB macro cioa the 


ample): a “a err rene : ANG fag? 
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- 


Example 


The example in Figure 10-24 has a window with a private de- 
vice context. When the program starts (WM_CREATE message 


received), the text color is set to blue. When the user clicks the 
“Do It!” menu item, the current color value is output in hexa- 


My Text Color= — 0000 
decimal. : 


The window’s class definition i in WinMain() includes the Figure 10-24. SetTextColor() 
CS_OWNDC style, giving the window its own private device and GetTextColor() Example. 
context. 


2 


generico 0 [7 fe. 


wndclass.style = CS_HREDRAW | CS_VREDRAW | CS_OWNDC ; wo 


Note that the RGB macro parameters are in the opposite order of the storage order inside the 
32-bit coded color value (compare RGB (0,0,255) with the output value of 0xFF0000). 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG tParam) 


“HDC 
DWORD 
char 


hDC ; 
darenteel ee ; 
cBuf C10) ; 


switch (iMessage) /* process windows messages */ 


{ 


[ Other program lines] 


case WM_CREATE: 


hDC = GetDC ChWnd) ; /* owns DC, no need to release */ 
Ssetlexttolor ChDC, RGB (0, 0, 255)) ; /* blue letters */ 
-break ; . 

case WM_ COMMAND: 

_ switch (wParam) 

{ 

case IDM_DOIT: /* usee hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
dwTextColor = Bet teurcotee ChDC) ; 
ltoa (dwTextColor, cBuf, 16) ; /* convert to hex */ 
TextoOut (hDC, 10, 10, “My Text Color =", 15) ; 
TextOut (hDC, 150, 10, cBuf, Lstrlen (cBuf)) ; 
break ; 


/* process menu items */ 


SETTEXT JUSTIFICATION mWin2.0 wWin30 wmWin3.1 


Purpose 
Syntax ‘ 
Description 


Uses 
Returns | 
See Also 


Justifies a string prior to using TextOut() for output. 


_ int SetTextJustification(HDC ADC, int nBreakExtra, int nBreakCount); 


Justification is the process of adding spaces between words to make a text string exactly fit a 
given space. SetTextJustification() works with the GetTextExtent() and TextOut() functions to 
accomplish this. GetTextExtent() is used to compute the length of the string before justification. 
SetTextJustification() then computes the amount of added space needed to match the space 
available. The next call to TextOut() uses this value to add spaces between words during output. 

Normally, the ASCII space character (number 32) is the break character. The break charac- 


. ters are where the extra spaces will be added. Some fonts may use another character as a break 


character. Use GetTextMetrics() to determine the font’s break character. If a line contains mul- 
tiple fonts, justify and output each group of characters, one font-type at a time. 
SetTextJustification() accumulates the round-off errors on each call in order to average the er- 
rors over the length of a line. Call SetTextJustification() with an nBreakExtra value of zero to 
clear the round-off error at the start of each new line. 


Justification of text. 


_int. TRUE (1) if successful, FALSE (0) on error. 


GetTextExtent(), TextOut(), ExtTextOut(), TabbedTextOut() 
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‘ Parameters. : 
— hDC HDC: The device context handle. : : 

nBreakExtra int: The total amount of extra space (in logical units) to be added to the line of text when output. 
In the default MM_TEXT mapping mode, the extra space is p= car ee: 
measured in pixels. Ec Th <7 a mariah 

nBreakCount int: The total number of break characters in the string. For 

most fonts, this is the number of space characters (““, or ASCII piieg qs 
32). SetTextJustification() will add additional room at each of 
these locations to expand the text. Figure 10-25. Text 
Example The example in Figure 10-25 justifies a three word string to fit Justification Example. 


exactly within the bounds of a 200 pixel wide rectangle. 
GetTextExtent() is used to calculate the size of the string prior to justification. SetText- 
Justification() then adds enough space to expand the string to the full 200 unit size. The next call 
to TextOut() uses the justification during output to space the words. | 

With this simple example, the number of spaces in the string (two) is known. Normally, you 
would have to check the number of spaces (break characters) in the string before calling 
SetTextJustification(). 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ m 


HDC hdc ; 

HPEN hPen ; 

DWORD dwExtent ; 

char cBuf £3 = {"“String To Fit"} ; 

switch (iMessage) /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 


Switch (wParam) 
{ 


case IDM_DOIT: /* User hit the “Do it" menu item */ , 
‘ hDC = GetDC ChWnd) ; ‘ 
. SetBkMode (hDC, TRANSPARENT) ; 
hPen = GetStockObject (BLACK_PEN) ; 
SelectObject (hDC, hPen) ; 
Rectangle (hbdC, 10, 10, 210, 50) ; 
dwExtent = GetTextExtent. (hDC, cBuf, 
strlen (cBuf)) ; 
SetTextJustification (hDC, 
200 - LOWORD(dwExtent), 2) ; 
TextOut (hDC, 10, 20, cBuf, strlen (cBuf)); 
ReleaseDC (hWnd, hDC) ; 


bs break ; 
[Other program lines] 
SETVIEWPORTEXT | wWin20 mWin30 mWin3.1 
Purpose Used with SetWindowExt() to set the scale of the logical coordinate system with the 
MM_ISOTROPIC and MM_ANISOTROPIC mapping modes. 
Syntax DWORD SetViewportExt(HDC ADC, int X, int Y); 
Description The MM_ISOTROPIC and MM_ANISOTROPIC mapping modes allow you to scale the logical co- 


ordinates system for a device context with ratio to the physical device coordinates (pixel based). 

’ MM_ISOTROPIC keeps both axes scaled equally, and MM_ANISOTROPIC allows both axes to be © 
scaled independently. 

In order to allow fractional scaling without using wileating point numbers, Windows uses two 

functions with two sets of integer values to scale the coordinates. SetWindowExt() can be thought 
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of as setting the physical coordinates, and SetViewportExt() sets the logical coordinates. It is the / 
ratio of the two sets of values that determines the scaling. If the signs for the X and Y values aré 
opposite, the orientation of the axes is reversed. This is usually used to make the Y axis increase 
upward, instead of the default system where Y values increase downward. 


Uses The MM_ISOTROPIC system is ideal for scaling drawings, without having to change. any of the 
dimensions used in the GDI function calls. The MM_ANISOTROPIC system can be used to scale 
the graphics in the client area to always fit within a sized window. The image will be distorted if 
the X and Y sizes are not changed equally (MM_ISOTROPIC preserves the image proportions). 

Returns DWORD, the previous viewport extents. The low-order word contains the X extent. The high- 

; order word contains the Y extent. Returns zero on error. 

See Also SetWindowExt(), SetMapMode(), SetViewportOrg(), SetWindowOrg() 

Parameters 

hDC HDC: The device context handle. . 

‘X int: The X axis extent. The X axis scaling is the ratio of this value divided by the.X parameter in 
SetWindowExt(). If the signs of the X parameters in SetWindowExt() and SetViewportExt() are 
opposite, X values will increase to the left. If the signs match, X values will increase to the right. 

Y int: The Y axis extent. The Y axis scaling is the ratio of this value divided by the Y parameter in 
SetWindowExt(). If the signs of the Y parameters in SetWindowExt() and SetViewportExt() are 
opposite, Y values will increase upward. If the signs match, Y values will increase downward. 

Example See the example under the ScaleViewportExt() function description. 

SETViewPorTORG gWin20 mWin30 mWin3.l 

Purpose Changes the origin of the coordinate system used for text and graphics locations on a device. 

Syntax DWORD SetViewportOrg(HDC hDC, int.X, int Y); | 

Description The origin of the coordinate system is the point that has location 0,0 for X and J 

: SetViewportOrg() allows you to place the origin anywhere in the client area. Note that the loca- 
tion of the origin is measured in device units. This is number of pixels measured from the upper ~ 
left corner of the device's client area. 

Uses In graphics routines, it is feqnentivit more convenient to have the origin at the middle 0 or bottom 
left of the client area’s rectangle. You can also move graphics on the screen by relocating the 
origin and then repainting. This is a way to scroll graphics images without recalculating where 
the points will be after scrolling. 

Returns DWORD, the previous origin measured in device units. The. X coordinate is in the low- order word, 
the Y coordinate is in the high-order word. 

See Also SetWindowOrg(), SetMapMode() 

Parameters 7 

hDC HDC: The device context handle. . Sto y pense ee 

x int: The new X location of the origin, measured in device units “[ Dott! Quit 

_ (pixels from the right side). 7” 

Y int: The new Y location of the origin, measured in es seen i la 
(pixels from the top, increasing downward). 50,50 MM LOMETRIC_ 

Related Messages WM_SIZE 

Example In Figure 10-26 a mapping mode is set with the origin at the 


~~» Jower left corner of the window's client area. The WM_SIZE Figure 10-26. SetViewport. 


messages are intercepted to find the size of the client areato Org() Example. 
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set the Y axis origin equal to the bottom of the client area. Because of the MM_LOMETRIC map- 
ping mode, Y increases upward. Note that by default the text locations are measured from the 
upper left corner of the first character of the string. That is why 50 logical units (5 mm) of vertical 
offset are needed to make the bottom line appear above the border. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
“HDC hdc ; 
static POINT ptClientSize ; 
switch CiMessage) /*®* process windows messages */ 
{ - 
case WM_SIZE: J/* get client area size */ 
ptClientSize.x = LOWORD (lParam) ; 
ptClientSize.y = HIWORD (lParam) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hbc = GetDC (hWnd) ; 
SetMapMode (hDC, MM_LOMETRIC) ; 
SetViewportOrg (hDC, 0, ptClientSize.y) ; ~~ 
TextOut ChDC, 50, 50, "50,50 MM_LOMETRIC", 17) ; 
TextOut (hDC, 150, 150, "150,150 MM_LOMETRIC", 19) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 

[Other program lines] 

SETWiInDOWEXT mw Win2.0 mWin30- mWin3.1 

Purpose Used with SetViewportExt() to set the scale of the logical coordinate system with the — 
MM_ISOTROPIC and MM_ANISOTROPIC mapping modes. . 

- Syntax DWORD SetWindowExt(HDC ADC, int X, int Y); . 

Description The MM_ISOTROPIC and MM_ANISOTROPIC mapping modes allow you to scale the logical coor- 
dinates system for a device context with ratio to the physical device coordinates (pixel based). 
MM_ISOTROPIC keeps both axes scaled equally, and MM_ANISOTROPIC allows both axes to be 
scaled independently. 

In order to allow fractional scaling without using floating point numbers, Windows uses two 
functions with two sets of integer values, to scale the coordinates. SetWindowExt() can be 
thought of as setting the physical coordinates, while SetViewportExt() sets the logical coordi- 
nates. It is just the ratio of the two sets of values that determines the scaling. If the signs for the 
X and Y values are opposite, the orientation of the axes is reversed. Reversing one axis is usually 
used to make the Y axis increase upward, instead of the default system where Y values increase 
downward. 

Uses The MM_ISOTROPIC system is ideal for scaling drawings, without having to change any of the 
dimensions used in the GDI function calls. The MM_ANISOTROPIC system can be used to scale 
the graphics in the client area to always fit within a sized window. The image will be distorted if 
the X and ¥ sizes are not changed equally (MM_ISOTROPIC preserves the image proportions). 

Returns DWORD, the previous window extents. The low-order word contains the X extent. The high-order 

7 word contains the Y extent. Returns zero on error. 
See Also SetViewportExt(), SetMapMode(), SetViewportOrg(), SetWindowOrg() 
Parameters 


HDC: The device context handle. 
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xX 


int: The X axis extent. The X axis scaling is the ratio of the X parameter in SetWindowExt() di- 


vided by this value. If the signs of the X parameters in SetWindowExt() arid SetViewportExt() are 
opposite, X values will increase to the left. If the signs match, X values will increase to the right. 
int: The Y axis extent. The Y axis scaling is the ratio of the Y parameter in SetWindowExt() di- 
vided by this value. If the signs of the Y parameters in SetWindowExt() and SetViewportExt() are 
opposite, Y values will increase upward. If the signs match, Y values will increase downward. 

Example See the example under ScaleViewportExt(). 

SETWInDOWORG m@Win2.0 mWin30 mWin3i 

Purpose Changes the location of the origin of the device context. 

Syntax DWORD SetWindowOrg(HDC hDC, int X, int Y); 

Description This is similar to SetViewportOrg(), except that logical units (not device units or pixels) are used. 

The point set is the logical offset of the upper left corner of the window’s client area, measured in 

logical units. , 

Uses Not used as often as SetViewportOrg(). . 

Returns DWORD, the previous origin of the window. The low-order word eontalit the X value, the high- 
‘order word contains the Y value. 

See Also SetMapMode(), SetViewportOrg() 

Parameters - ; 

hDC HDC: The device context handle. 

X int: The newX location of the origin, measured in logical units. 

Y int: The new ¥ location of the origin, measured in logical units. 

Example ‘This example sets the logical origin in the center of the window’s client area. This is complicated 


slightly because SetWindowOrg() uses logical units to set the origin, not device units (pixels). 
The size of the client area returned when a WM_SIZE message is processed in device units, which 
are converted to logical units using the DPtoLP() function. Finally, the window origin is set using 
SetWindowOrg(). The origin dimensions are both negative because we are setting the logical 
value of the upper left corner of the window, measured in the MM_LOMETRIC units of .1 mm. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC 
static 


switch (iMessage) 
{ 


[Other program lines] 


; : hoc ; 
POINT ptClientSize, ptCenter ; 


/* process windows messages */ 


case WM_ SIZE: 
ptClientSize. x 
ptClientSize. y 
break ; 

case WM_ COMMAND: 
switch GiPareand 


/* get client area size */ 
LOWORD (lParam) ; 
HIWORD (lParam) ;. 


/* process menu items */ 


vease IDM_DOIT: /* User hit the "Do it" menu item */ 
ADC = GetDC (hWnd); 
SetMapMode ChDC, MM_ LOMETRIC) ; : 
ptCenter.x = ptClientSize. x / 3. ;/* cale center in */ 
ptCenter.y = ptClientSize. y /2 o/* device units */ 
DPtoLP ChDC, &ptCenter, 1) ; /* convert to log units */ 
SetWindowOrg Choc, -ptCenter. x, ~ptCenter.y) ; 
TextOut. Choc, 0, 0, "0,0 MM_LOMETRIC", 15) ; 
TextOut ChDC, 150, 150, "150,150 MM_LOMETRIC", 19) > 
ReleaseDC (hWnd, hDC) ; 
break ; 7 


428 


10. DEVICE CONTEXTS, TEXT OUTPUT, AND PRINTING -¥ 


TABBEDTEXTOUT Win2.0 mWin3.0  mWin31 

Purpose Outputs a text string, expanding all tab characters. 

Syntax long TabbedTextOut(HDC ADC, int_X, int Y, LPSTR lpString, int nCount, int nTabPositions, 
LPINT IpnTabStopPositions, int ‘nTabOrigin); 

Description . This is an extension of the TextOut() function that adds the ability to expand tab characters to 

- any set of tab positions. ; 

Uses Text output when the text string contains tab characters. Tabs are used to align text in columns. 

Returns long, the logical dimensions of the string output. The low-order word contains the width, the 
high-order word contains the height. 

See Also TextOut(), GetTabbedTextExtent(), SetTextAlign(), SetBkMode(), SetTextColor() 

Parameters 

hDC HDC: The device context handle. 

Xx int: The logical X coordinate to start the string. 

Y int: The logical Y coordinate to start the string. 

lpString LPSTR: A pointer to a character string that will be output. 

nCount int: The number of characters, including tab characters, in the string. 

nTabPositions int: The number of tab positions specified in lpnTabStopPositions. . 


. lonTabStopPositions LPINT: A pointer to an array of integers that holds 


nTabOrigin 


| Related Messages 
Example 


the tab stop positions. The tab positions are mea- [S50 gence CES 
sured in deviee units (pixels), and must be in as- os : 
cending order. 


First- Field 1 Field2 Last Field 
int: The logical X coordinate to start tab expan- Second-Field1  Field2 The End 


sions. You can use TabbedTextOut() several times 
on one line by changing the nTabOrigin parameter Figure 10-27. TabbedTextOut() 
to start the tab expansion from different X locations. Example. 


WM_PAINT 


The example in Figure 10-27 outputs two lines of text and expands the tab characters in the 
strings. ; 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
HDC hoc ; 
static char cBuf1 CI] = ("First - Field 1\tField 2\tLast Field"} ; 
static char cBuf2 LJ = ("Second - Field 1\tField 2\tThe End"} ; 
static int nTabs CJ] = (30, 45, 60} ; 
switch CiMessage) /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the “Do it™ menu item */ 


[Other program lines] 


hDC = GetDC (hWnd) ; 

TabbedTextOut (hDC, 10, 10, cBufi1, 
istrlen (cBuf1), 3, 
(LPINT) &nTabs, 10) ; 

TabbedTextOut (hDC, 10, 30, cBuf2, 
Lstrlen (cBuf2), 3, 
-CLPINT) &nTabs, 10) ; 

ReleaseDC (hWnd, hdC) ; 

break ; © : 
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TeExTOuT | mWin2.0 m8 Win30 mWin31 

Purpose Outputs a character string at a location on the selected device context. 

Syntax - BOOL TextOut(HDC hDC, int X, int Y, LPSTR lpString, int nCount); 

Description This is the standard text output function. The text is output with the currently selected font, pen 
color, and background color. 

Uses Used for text output where the character string does not contati tab characters. Use 
TabbedTextOut() if the tabs need to be expanded. 

Returns BOOL. TRUE if the string was output, FALSE on error. 

See Also SetTextAlign(), TabbedTextOut(), SetBkMode(), SetTextColor(), SetTextCharacterExtra() 

seen” 

Parameters . 

hDC HDC: The device context handle. ~ 

4 int: The logical X coordinate to start the string. 

Y int: The logical Y coordinate to start the string. 

lpString LPSTR: A pointer to a character string that will be output. 

nCount int: The number of characters in the string. Use the Istrlen() function to determine this value for 


null-terminated strings. 
Related Messages WM_PAINT 


Example This example ee the string “This is a character string.” when the user hits the “Do It!” menu 
. item. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC hDC ;. ; 
char cBuf C1] = {"This is a character string."} ; 


switch (iMessage) /* process Windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) , 
{ 


case IDM_DOIT: /* User pve. the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
TextOut (hDC, 10, 10, cBuf, Lstrlen SOREN 
Re Lessede Chuind, hdc) ; 


break ; 
[Other program lines] 
WSPRINTF — OWin2.0 mWin30 mWin3.l 
Purpose Formats text output to a character buffer. 
Syntax int wsprintf(LPSTR IpOutput, LPSTR lpFormat|, argument)...);__ 
Description This is the Windows version of the standard C library sprintf() function. The format string defines 


what the output should look like, and includes special characters as placeholders for numbers 
and characters that are passed to the function as arguments. Because wsprintf() will accept a 
variable number of arguments, it does not use the standard Windows function calling convention 


«of PASCAL. 
Uses Formatting text output, especially text containing numbers. 
Returns int, the number of characters output to lpOutput. 
- See Also wvsprintf(), TextOut(), TabbedTextOut(), ExtTextOut() 


430 


Parameters 
lpOutput 
lpFormat 


argument 
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LPSTR: A pointer to a character buffer to hold the output. 


LPSTR: A pointer to a null-terminated character string that contains the format. This can in- 
clude the special characters listed below. 


(variable type): One or more optional arguments. The number and type of these arguments is 
specified by the special characters used in IpFormat. 


Format Characters A typical format string is 


A number = %d, a name 4s. 


The %d is a code for decimal integer, the %s for string. The arguments following the format string 
would then include the number and a pointer to a character. These values would be inserted into 
the format string in place of the %d and %s as the string is formatted into the /pOutput character 
buffer. The list of character codes appears in Table 10-15. 


Meaning 


%c 
od, %i 
%ld, li 
You 
%lu 
%ox, YX 


lx, %IX 


Insert a character string at the location. The argument corresponding to this location must be passed as a 
long pointer to a string (LPSTR). Be sure to cast ame as LPSTR when using this type. 


Insert a signed character af the location. 

Insert a signed integer at the location. 

Insert a signed long integer at the location. 
Insert an unsigned integer at the location. 
Insert an unsigned long integer at the location. 


Insert an unsigned hexadecimal integer at the location. The uppercase X results in uppercase A-F digits as 
part of the hexadecimal output. 


Insert a long unsigned hexadecimal integer at the location. whe uppercase X results in uppercase A- F digits 
as part of the hexadecimal output. , 


Table 10-15. wsprint{() Format Codes. 


Additional formatting information can be included between the % and the format letter(s). 


: For example, the format code “%06d” specifies that the field is to have six digits and leading zeros 
..., . are to be added to fill up the six spaces. The list of these extra formatting characters appears in 
_, Table 10- 16. 


° Meaning‘ 


Anumber 


Justify to the left. Normal, iustiicaton| is to the font i side. 


_,, Put Ox or OX in front of hexadecimal numbers, Tee 
"Bad the output with zeros instead of blanks. 


._ The number of digits or characters to display. If no value is given, the field is seaided to make room for 
the number or string passed as an argument. 


Table 10-16. wsprint{() Extra Formatting Codes. | 


. Example 


{ 


HDC 


aan 2 44, 
eee af Sprite rane ae 


. This example uses wsprintf() to forinat a aeelts containing two integers the re height anid width of 


the client region when the user clicked the “Do It!” menu item. The formatted ve is stored inthe 
cBuf{] buffer, and then.output.to the screen with TextOut(). 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, :LONG lParam) 


Be ish 
2 RR 


hDC ; 
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RECT rClient ; 
char cBuf [128] ; 
switch (iMessage) /* process windows messages */ | 
{ 5; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
' GetClientRect (hWnd, (CLPRECT) &rClient) ; 
wsprintf (cBuf, 
"The client rectangle is %d wide by %d tall.", 
rClient.right - rClient. left, 
rClient.bottom ~ rClient.top) ; 
TextOut (hDC, 10, 10, cBuf, Lstrlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
[Other program lines] 
WVSPRINTF OWin2.0 mWin30 mWin31 
Purpose Formats text output to a character buffer. 
Syntax . int wvsprintf{(LPSTR /pOutput, LPSTR lpFormat, LPSTR lpArglist); - 7 
Description This is the Windows version of the standard C library vsprintf() function. The format string de- 
fines what the output should look like, and includes special characters as placeholders for num- 
bers and characters that are passed to the function as arguments. vwsprintf() uses a pointer to an 
argument list to avoid having a variable number of arguments. It uses the standard Windows 
function calling convention of PASCAL. 
Uses Formatting text output, especially text containing numbers. 
Returns int, the number of characters output to /pOutput. 
See Also wsprintf(), TextOut(), TabbedTextOut(), ExtTextOut() _ 
Parameters cee 
lpOutput LPSTR: A pointer to a character buffer to hold the output. 
lpFormat LPSTR: A pointer to a null-terminated character string that contains the format. This can in- 
clude the special characters listed previously under the wsprintf() function description. 
lpArglist LPSTR: A pointer to an array of WORD values. Each WORD either specifies a numeric value or 


contains a pointer to a character string. Long values and character pointers require two words of 
storage. For long values, the low-order word is first in the array, followed by the high-order word. 
For character pointers, the segment is first in the array, followed by the offset. 


Format Characters See the list under the function description for wsprintf(). 


Example 


This example uses wvsprintf() to privat astring with two armament an integer and a scliliucter 
string. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
; HDC hoc ; : 
-static int - nData = 666 ;. 

static char cString CJ] = “Argument Data" ; 

WORD wArgs £3] ; 

char cBuf C128] ; 

switch CiMessage) /* process windows messages */~ 

case WM_COMMAND: /* process menu items ,*/ 

switch (wParam) : 
t 
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case IDM_DOIT: /* User hit the “Do it" menu item */ 
hOC = GetDC (hWnd) ; 
wArgs CO] = nData ; 
wArgs £1] = (WORD) cString ; 
wArgs C2] = HIWORD CCLPSTR) cString) ; 
wysprintf (cBuf, 
"The number = Z“d, the string = Zs", 
CLPSTR) wArgs) ; 
TextOut (hDdC, 10, 10, cBuf, Lstrlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 


[Other program lines] 
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Windows provides a wide range of functions to simplify the task of painting objects on a device context. In the last 
chapter, we examined the functions for creating and displaying text characters and fonts. This chapter includes the 
remaining painting functions for rectangles, lines, ellipses, polygons, and regions, which are all elements of the Win- 
dows GDI (Graphics Device Interface). Windows provides a rich collection of functions for painting shapes. In many 
cases, there is more than one way to paint a given shape. This can be a little confusing when you start programming in 
Windows. Don’t be intimidated by all of these functions, In most cases, you will need only a handful of them for any one 
application. Only graphics-intensive programs, such as CAD/CAM and paint programs, will put a paid of these 
functions to work. 


The WM_PAINT Message 


We briefly looked at the WM_PAINT message in the last chapter under the discussion of device contexts. This section 
goes into more details on handling this important message. When any part of a window's client area needs to be 
repainted, Windows sends the application a WM_PAINT message. The program logic for painting tte window’s client 
area normally will be in response to WM_PAINT. 

Unlike most Windows messages, WM_PAINT messages do not encode any information | in the [Param or wParam 
parameters that are passed with the message. Instead, Windows provides two functions that are always used in pro- 
cessing WM_PAINT messages, BeginPaint() and EndPaint(). All programs processing WM. PAINT messages will use 
these two functions in sequence, as shown in Listing 11- 1. 


© Listing 11-1. Typical WM_PAINT Logic 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
Pi : 


PAINTSTRUCT ps ; 


switch CiNessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
/* the painting logic goes in here */ 
EndPaint (hWnd, &ps) ; 
break ; 
/* the rest of the WndProc() function */ 


BeginPaint() fills the values in a PAINTSTRUCT data structure, which is defined in WINDOWS.H as | 
typedef struct tagPAINTSTRUCT 
{. 


HDC. hdc; * /* device context handle */ 
BOOL fErase; /* background redrawn? TRUE/FALSE */ 
RECT rcPaint; /* RECT of client area update rect. */ 
BOOL fRestore; /* reserved */ 
BOOL fIncUpdate; /* reserved */ 
BYTE rgbReserved[161]; /* reserved */ 

> PAINTSTRUCT; . 

typedef PAINTSTRUCT *PPAINTSTRUCT; 
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typedef PAINTSTRUCT NEAR *NPPAINTSTRUCT; 
typedef PAINTSTRUCT FAR *LPPAINTSTRUCT; 

Only the first three elements in the PAINTSTRUCT data structure are ised by the application program. The 
remainder are reserved by Windows. The Adc element is the device context for the window's client area. The fErase — 
element is a flag which is TRUE if the background of the window has been redrawn, FALSE if it has not been. The 
rcPaint element is a pointer to a rectangle that contains the part of the client area that will be repainted, which is 
called the “invalid” area of the window. 


Invalid Rectangle 

The invalid part of a window is an important concept. Consider a case where the application scrolls the client area of 
the window upward by 10 pixels. Only the bottom ten pixels need to be painted to keep the client area up-to-date. The 
rest of the client area is the same, just repositioned upward. 

For efficiency in repainting, Windows keeps track of the size of the smallest rectangle on the client area that 
includes all of the area that must be repainted. That rectangle’s size is put into the rcPaint rectangle passed with the 
PAINTSTRUCT element. The BeginPaint() function fills in the rcPaint values. When an application processes 
WM_PAINT messages and paints in the client area, only the invalid part of the client area is repainted. This is true 
even if the painting commands for lines, rectangles, etc. have areas outside of the invalid region. Windows just ignores 

* the parts of the lines, etc. that fall outside of the invalid rectangle. . 

You do not have to concern yourself with the size of the invalid rectangle when writing your application. Most 
programs have logic that repaints the entire client area every time a WM_PAINT message is received. The fact that 
only the invalid part of the client area is physically changed is of little consequence. However, you might want to 
evaluate the invalid rectangle if painting the client area is taking too much time. In this case, you can repaint portions 
of the client area separately, painting only the parts that are invalidated. This is a good way to speed up scrolling 
operations. Other situations will not be improved by evaluating the invalid rectangle. For example, when a window is 
resized, the WM_PAINT message is passed with the entire client area invalidated. 

Another way to speed up a program is to inhibit Windows from sending WM_PAINT messages when they are not 
needed. For example, if you scroll the client area, the area will become invalid. Windows will put a WM_PAINT mes- 
sage on the application’s message queue to update the invalid region. To stop this from happening, use ValidateRect() 
or ValidateRgn() to validate the area. This technique only works outside of the WM_ PAINT part of the application’ 8 
logic. BeginPaint() automatically validates the invalid rectangle. 

The opposite situation occurs when you want to force Windows to send a WM_PAINT message. InvalidateRect() 
and InvalidateRgn() can be used to invalidate some or all of the client area. Used alone, these functions result in a 
WM_PAINT message being placed on the application’s message queue. You can force an immediate WM_PAINT mes- 
sage by following the functions with a call to UpdateWindow(). UpdateWindow() sends the WM_PAINT message di- 
rectly to the application, bypassing the message queue. 


The Device Context 


All painting to a device context requires the device context handle. We have been using GetDC() and ReleaseDC() to 
retrieve the handle outside of the WM_PAINT logic. BeginPaint() and EndPaint() do the same function inside the 
WM_PAINT processing part of the program. There are two ways to get the device context handle when processing 
WM_PAINT messages, One way is to make use of the hdc element of the PAINTSTRUCT data structure that is updated 
by BeginPaint(). This typically looks something like Listing 11-2. . 


& Listing 11-2. Using the BeginPaint() Device Context Handle 
tong FAR PASCAL WndProc CHWND hWnd, unsigned iHessage, WORD wParam, LONG LParam) 


PAINTSTRUCT ps ; 
{ ’ 
switch (iMessage) - /* process windows messages */ 
{ os : 
case WM_PAINT: 


BeginPaint (hWnd, &ps) P| 
TextOut (ps.hde, 10, 10, "Hi There!", 9) ; 
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EndPaint (hWnd, &ps) ; 
break ; 
/* the rest of the WndProc() function */ 


This style is used in the examples in this chapter. The other way to get the device context handle is to take 
advantage of the fact that BeginPaint() returns this value. That style of Vee looks like the code in Listing 
11-3. 


© Listing 11-3. Using the BeginPaint() Device Context Handle 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


PAINTSTRUCT ps ; 

HDC hoc ; 

switch (iMessage) /* process windows messages */ 
{ 


‘case WM_PAINT: 
hDdC = BeginPaint Chiind, &ps) > 
TextOut (hDdC, 10, 10, cr There!", 9) ; 
EndPaint (hWnd, &ps) 3 
break ; 
/* the rest of the WndProc() function */ 


Both methods have the same effect. Note that you do not call ReleaseDC() after BeginPaint(). EndPaint() takes 
care of releasing the device context. 


Selecting Objects into the Device Context 


Up to this point, we have used the device context as a means to draw-text on the screen. It turns out that the ee 
context can hold much more information than just text attributes. At any one time, a device context will contain a 
font, pen, and brush. It may also contain a region and a color palette. When you draw a line using a device context, the 
color, size, and type of line are all determined by what 
type of line you have “selected into” the device context. 
Selecting an object, such as a pen, makes that pen avail- 
able to every drawing function that uses a pen: The se- 
lected pen will be used for lines and for the borders on 
rectangles, ellipses, and polygons. 

At any one time, a device context can have only one 
type of each object (pen, brush, font, region, palette) se- 
lected. If you select a new object, the old one of the same b> “a 
type is bumped out. You must avoid deleting objects in es = { Palette | 
an active device context. Always keep one of each object 
selected at all times. The objects do not physically reside Figure 11-1. Objects Selected into a Device Context. 
in the device context. Objects are created and stored in 
separate memory areas. Selecting an object passes the pointer to the device context so that Windows’ GDI functions 
can make use of the object. (See Figure 11-1). 

- To use an object with a device context, you must create the object and then select it. For example, to draw a 
rectangle with a blue border (pen) and a red hatched pattern interior, the program logic would look something like 
Listing 11-4, which is illustrated in Figure 11-2. 


> Listing 11-4. Selecting a Pen and a Brush into the Device Context 
_long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : : z I 


PAINTSTRUCT ps ; 
HPEN . hPen, hOldPen; 
HBRUSH hBrush, hOldBrush ; 
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switch (iMessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hPen = CreatePen (PS_SOLID, 3, RGB (0, 0, 255)) ; 
hBrush = CreateHatchBrush CHS_DIAGCROSS, 

RGB (255, 0, 0)) ; 

hOlLdPen = SelectObject (ps.hdc, hPen) ; 
hOldBrush = SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 20, 20, 100, 70) ; 
SelectObject (ps.hdc, hOldPen) ; 
SelectObject (ps.hdc, hOldBrush) ; 
DeleteObject (hPen) ; 
DeleteObject (hBrush) ; 
EndPaint ChWnd, &ps) ; 
break ; 


Note that the pen and brush are deleted after use to avoid filling up system 
memory. The memory associated with GDI objects will continue to be occupied even 
if the application program is terminated, so always be sure to delete pens, brushes, 
fonts, regions, and palettes after use. Objects cannot be deleted if they are attached 
to a device context. Either delete them after the device context is released 
(EndPaint() called) or select a stock object into the device context first to displace 
the object you wish to delete. 

The example in Listing 11-4 demonstrates a foolproof way to make sure that 
objects are not deleted from an active device context. When an object is selected 
into the device context, SelectObject() returns a handle to the object that is being —Lexsamssmsmm a 
displaced. This “old” object handle can be saved, and then selected back into the Figure 11-2. Example Use of 
device context when you are through with the “new” object. Selecting the “old” a Pen and Brush Object. 
object again makes it safe to delete the “new” object. This type of logic is usually 
used when the window maintains its own private device context. 


Default and Stock Objects | 


When you first get a handle to a device context, it will contain handles to predefined objects that are always aeullabie: 
which are called “stock objects.” The default pen is a solid black line, one pixel wide. The default brush is a solid white 
brush. The default font is a black system font. These default objects have allowed us to use the TextOut() function 
without specifying the color or font to use. The default values for the device context were applied. You can also use 
GDI functions, such as Rectangle(), without selecting a line or brush style. By default, the rectangle will be painted 
with a thin black outline and filled on the interior with the default white brush. You can get a handle to the stock 
objects by using GetStockObject(). Don’t try to delete these objects after use—they are part of the Windows GDI. 

A good reason for selecting a stock object is to displace another similar object out of the device context. Remem- 
ber that a device context will contain at most one of each type of object. If you want to get rid of a special pen, but still — 
use the device context, use a function call such as 


Dolt! Quit : 


hOLdPen = SelectObject (ps.hdc, GetStockObject (BLACK_PEN)) ; 


Selecting the stock black pen displaces whatever pen was in the device context before. The value returned by 
SelectObject() is a handle to the previous object, in this case the previously selected pen. This returned value can be 
used to delete the object (pen), if it is no longer needed and is not a stock object. Remember that once an object is 
selected, it is used by every painting function that uses the device context. For example, selecting a brush will result 
in that brush being used to fill all rectangles, ellipses, polygons, and regions until a new brush is selected. 

The device context “forgets” which objects were selected after the device context is released. You will have to 
select pens, etc. every time a device context handle is obtained with either BeginPaint() or GetDC(). Alternatively, 
you can sav’> one or more device cdntexts with SaveDC() in a “context stack.” This technique is described in Chapter _ 
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10, Device Contexts, Text Output, and Printing. You can also maintain a private device context for the window or 


window class by defining either the CS_OWNDC or CS_CLASSDC styles i in the RegisterClass() function call. Thisis 


described i in Chapter 2 Lisi Windows. 


Windows encodes colors using three values. The values 


‘correspond to the intensity of the Red, Green, and Blue = Figure 11-3. COLORREF RGB Color Values. 
elements that make up any color. This coding is called 
“RGB” color. Windows limits the color values to between 0 and 255 for each of the three colors. RGB ee are 
“encoded into a 32-bit value, called a COLORREF. The red, green, and blue values are stored in the lower three bytes of 
the 32 bits as shown in Figure 11-3. The most significant byte is used only with palette colors, which are discussed in 
the subject of the next chapter: 
Windows provides several macros for manipulating these 32-bit color values. The RGB macro is the most fre- 
quently used. It takes the three color values for red, green, and blue intensity as parameters and combines them into 
a single 32-bit value. For example, to create a pure blue pen, use 


COLORREF crColor ; 
erColor = RGB (255, 0, O) ; 


The opposite conversion extracts a single color value from the combined 32-bit color by using the GetBColor(), 
GetGColor(), and GetRColor() macros for the blue, green, and red color elements, respectively. These macros are 
included in the function descriptions in this chapter. 

' Inpractice, most displays can show a limited number of pure colors. A typical VGA display can show only 16 pure 
~ colors at one time. Windows partially gets around this limit by “dithering”, the process of mixing the pixels to get an 
average color close to the pure color requested. For example, the creation of a brush with the following function call 
will result in a dithered brush pattern with a blue-green average color. 


HBRUSH ~ hBrush ; 
hBrush = Kvestesoderuck CRGB (20, 117, 55)) ; 


If you will be supporting more advanced video equipment, such as the IBM 8514 or a Super VGA adapter, Windows 
provides support for specifying pure colors. This support is implemented by selecting a palette into the device context 
and using the colors defined by the program for the palette. This subject is covered in the next eee Color Pallete 

‘Control. 


Regions a 
A powerful element of the Windows GDI is the concept of a “region.” Regions are § ~genernic: [~ [= 
areas on the device that can be used as boundaries to painting. Regions can have ; Dolt! Quit = | 
any shape, Complex regions can be built by combining small areas made of ellipti- = —{-—— = = 
cal regions, rectangular regions, and polygon regions. A single, logical region can 
contain several areas that do not touch. Consider the task of creating a picture like 
the one shown in Figure 11-4, The brute force method of painting this type of figure 
would be to calculate the length of a series of black lines that would be used to build ee - 
- up the shapes. This would end up being a slow process. 
The elegant way of creating this shape is to create a region, called a “clipping Figure cs Comp ue 
region,” that defines the areas that will be painted and excludes the rest of the 
client area. All painting operations are “clipped” so that only the Part of the painted 
object within the clipping region is painted. a 
In this case, the region is created by logically combining an elliptical region and a rectangular region. The 
CombineRgn() function does the work. Once the region is created, it is set up as the clipping region for the device 
context with SelectClipRgn(). All painting after that is restricted to the interior of the region. For more details on 
regions, look at the explanations for the CreateRectRgn(), CreateEllipticRgnQ), CombineRgn(), and SelectClipRenQ) ~ 
: functions, 


Region. 
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ane 
Ree 


OR rere 


Arc 
BeginPaint 


Chord 


CombineRgn 
CopyRect 
CreateBrushindirect 
CreateEllipticRgn 


CreateEllipticRgnindirect 


CreateHatchBrush 
CreatePattemBrush 
CreatePen . 
CreatePenindirect 
CreatePolygonRgn 
CreatePolyPolygonRgn 
CreateRectRgn 
CreateRectRgnindirect 
CreateRoundRectRgn 
CreateSolidBrush 
DeleteObject 
DrawFocusRect 
Ellipse 

EndPaint 
EnumObjects 
EqualRect 

EquaiRgn 
ExcludeClipRect 
ExcludeUpdateRgn 
ExtFloodFill 

FilRect 

FillRgn 

FloodFill 

FrameRect 
FrameRgn 
GetBrushOrg 
GetRValue - 
GetClipBox 
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Draws an elliptical arc using the selected pen. 
Prepares the window's client area for painting. 

Draws a chord segment with the selected pen, and fills the interior with the selected brush. 
Logically combines two regions into one region. | 

Copies the coordinates of one rectangle into another. 

Creates a brush from a bitmap or stock brush shape. 

Creates an elliptically shaped region. 


Creates an elliptical region based on the bounding rectangle described in a RECT data 
structure. 


Creates a brush based on a predefined pattern. 

Creates a brush based on a bitmap. 

Creates a custom pen. 

Creates a pen based on LOGPEN data. 

Creates an arbitrary shaped polygonal region. 

Creates a region composed of multiple polygons in a singie function call. 
Creates a rectangular region. 

Creates a rectangular region based on the data in a RECT data structure. 
Creates a rectarigular region with rounded corners. | 
Creates a brush with a solid color. 


_ Removes pens, brushes, fonts, bitmaps, regions, and palettes from memory. 


Draws or removes a dashed line around a rectangie. 

Draws an ellipse. ° 

Ends the painting cycle started by BeginPaint(). 

Enumerates all of the pens or brushes available on a device context. 
Checks if two rectangles are equal. 

Checks if two regions are equally sized. 


~” Removes a rectangular area from a clipping region. 


Prevents drawing in invalid areas of the client area. 

Fills an area by replacing a color with the currently selected brush. 
Fills a rectangular area with a brush pattern and color. 

Fills a region with a brush color and pattem. 

Fills an area with the currently selected brusn. 

Draws a frame around a rectangle using a brush. 

Draws a frame around a region using a brush pattem. . 

Finds the brush origin of a device context. 

Retrieves the red color value from a 32-bit color value. | 
Gets the dimensjons of the smallest rectangle that wit enclose the clipping region. 


\ 
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Table 11-1. contin ned 
‘Function = 
GetCurrentPosition 
GetNearestColor 


GetObject 
GetPixel 


GetPolyFillMode 


GetRgnBox 
GetROP2 


GetStockObject 


GetSysColor 
GetUpdateRect 
GetUpdateRgn 
InflateRect 


IntersectClipRect 


IntersectRect 
InvalidateRect 
InvalidateRgn 
InvertRect 
InvertRgn 
IsRectEmpty 
LineDDA 
LineTo 
MAKEPOINT 
MoveTo 
OffsetClipRgn 
OffsetRect 
OffsetRgn 


~. PaintRgn | 


Pie 

Polygon 
Polyline 
PolyPolygon 
PtinRect 
PilnRegion 
PtVisible 
Rectangle 
RectInRegion 


Purpose oi 
Determines the current logical position in a device context. 
Determines the closest solid color a device can display. 
Retrieves information about an object. 

Determines the color of a pixel. 

Determines the current polygon filling mode for a device context. 

Determines the bounding rectangle of a region. 

Determines the current raster drawing mode for a device context. 

Retrieves a hancle to one of the predefined objects that are always available to Windows 


applications. 


Retrieves one of the system colors. 

Retrieves the dimensions of the invalid rectangle in the window’s client area. 
Copies the update region of a window's client area to another region. 
Increases or decreases the size of a rectangle. 
Creates a new clipping region by combining the existing rectangle and a rectangular region. 
Compites the rectangle of the intersection of two other rectangles. 

Adds a rectangular area to a window's update region. 

Adds a region to a window's update region. 

Inverts the color of every pixel within a rectangular area. 

Inverts the color of every pixel within a region. 

Determines if a rectangle has a height or width of zero. 

Draws a line with a custom drawing procedure. 

Draws a line from the current location to a new point. 

Converts from a DWORD value to a POINT structure. 

Moves the current position to a new location, ready to draw a line. 

Moves the clipping region. 

Shifts a rectang}e in the X and Y directions. 

Moves a region. 

Paints a region with the currently selected brush. 

Draws a pie-shaped wedge. 

Draws a polygon. 

Draws a line with multiple segments, 

Draws one or more polygons. 

Determines if a point is within a rectangular area. 

Determines if a point is within a region. 

Checks if a point is within the clipping region. | 

Draws arectangie. ° , a 


"Checks if a rectangle is within a region. 
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RectVisible 
RGB. 
RoundRect 
SelectClipRgn 
SelectObject 
SetBrushOrg 
SetPixel 
SetPolyFillMode 
SetRect 
SetRectEmpty 
SetRectRgn 
‘SetROP2 
SetSysColors 


UnionRect 


UnrealizeObject 
UpdateWindow 
ValidateRect 
ValidateRgn 
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Checks if a rectangle has points within the current clipping region. 
Creates a 32-bit color value given the three primary cclor elements. 
Draws a rectangle with rounded corners. 

Uses a region to clip output to a device context. 

Selects an object into a device context. 

Changes the origin used by the device context to line up pattern brushes. 
Changes to color of a single point on the device context. 

Changes the polygon filling mode of a device context. 

Enters all four values for a RECT data structure. 

Sets all of the elements of a RECT data structure to zero. 

Changes the bounds of a rectangular region. 

Changes the raster drawing mode of a device context. 


Changes the color values Windows uses ato paint background and nonclient areas of the screen 
and windows. “ 


Sets the size of a rectangle equal to the smallest rectangle that will enclose two other 
rectangles. 


Resets a brush origin, or a palette. 

Forces an immediate WM_PAINT message, updating the window. 
Remove? a rectangular area from the window's update region. 
Removes a region from the window’s update region. 


Table 11-1. Painting Function Summary. 


Painting Function Descriptions 
This section contains the detailed function descriptions of functions used in apainitie a device context. 


ARC 
Purpose 
Syntax 


! 


Description 


Uses 
Returns 
See Also 


Parameters 
hDC 


Al 
Y] 


; @Win2.0 mWin30 wmWin3l 
Draws an elliptical arc using the selected pen. , 
BOOL Are(HDC ADC, int X/, int Y/, int X2, int Y2, int X3, int ¥3, int_X4 , int Y4); 


An elliptical arc is a section from an ellipse. The Arc() function specifies the X, Y coordinates of 
the bounding rectangle and two other points that define the start and end points of the arc. The 
start and end points (X3, ¥3 and X4, Y4) do not have to fall on the arc. Windows computes the start 
of the arc by calculating a line from the specified start point to the center of the bounding rect- 
angle. The intercept of this calculated line and the arc’s line is used for the start point. The same 
logic is used to calculate the end point of the arc. 


Sections of an ellipse can be used as a general way to draw lines with changing curvature. 
BOOL. TRUE if the are was drawn, FALSE on error. 
SelectObject(), DeleteObject, CreatePen(), BeginPaint(), EndPaint() 


HDC: The device context handle. 
int: The logical X coordinate of the upper left corner of the bounding rectangle. 
int: The logical Y coordinate of the upper left corner of the bounding rectangle. 
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X2 int: The logical Xcoordinate of the lower right corner of the (agg 
bounding rectangle. . . fr} generic ~ [~ [= 

Y2 int: The logical Y coordinate of the lower right corner of the | Dolt! Quit | 
bounding rectangle. : : : 

X3 int: The logical Xcoordinate of the starting point of the arc. 

Y3 int: The logical Y coordinate of the starting point of the arc. 

x4 int: The logical Xcoordinate of the ending point of the arc. 

Y4 . int: The logical Y coordinate of the ending point of the arc. 

Related Messages WM_PAINT ; 

Example: This example, as shown in Figure 11-5, paints the client area . j 


with a red arc. The bounding rectangle is also shown as a thin 6 ae 
line, just to clarify how the Arc() function works. The start and Figure 11-5. Arc() Example. 
end points of the arc are specified as the lower left corner of 

the rectangle and the top center. Note that the lower left corner does not fall on the arc’s line. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps; 

HPEN . hPen ; 

switch CiMessage) /* process windows messages */ 
{ 2 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SelectObject (ps.hdc, GetStockObject (BLACK_PEN)) ; 
Rectangle (ps.hdc, 10, 10, 110, 110) ; /* bounding rect */ 
hPen = CreatePen (PS_SOLID, 4, RGB (255, 0, 0)) ; 
SelectObject (ps.hdc, hPen) ; /* select a thick red pen */ 
Arc (ps.hdc, 10, 10, 110, 110, 10, 110, 60, 10) ; 
EndPaint (hWnd, ps) ; 
DeleteObject (hPen) ; 


break ; 
[Other program lines] 
BEGINPAINT v wWin2.0 mWind.0 mw Win31- 
Purpose Prepares the window's client area for painting. ae 
Syntax HDC BeginPaint(HWND hWnd, LPPAINTSTRUCT lpPaint); 
Description BeginPaint() is used to retrieve the device context handle for the window's client area A wile 


processing a WM_PAINT message. This is the only time BeginPaint() is used for this purpose. 
GetDC() is used anywhere else in the program to get the hDC device context handle. Begin- 
Paint() fills in the data in a PAINTSTRUCT data structure. This is defined in WINDOWS.H as 


follows: " 
f 


typedef struct tagPAINTSTRUCT 
{ 


HDC” hdc; /* device context to paint */ > 
BOOL fErase; - /* TRUE if background has been redrawn */ / 
RECT rcPaint; /* update rectangle */ 
sO0OL fRestore; /* reserved */ 
BOOL fIncUpdate; . 7* reserved */ 
BYTE rgbReserved(16]; /* reserved */ 
} PAINTSTRUCT; 
typedef PAINTSTRUCT | *PPAINTSTRUCT; 
typedef PAINTSTRUCT NEAR *NPPAINTSTRUCT; 


typedef PAINTSTRUCT FAR. *LPPAINTSTRUCT; 
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You can either use the returned value from BeginPaint() as the client area device context 
handle, or use the hdc element of the paint structure. Both handles are the same. The {Erase 
element is TRUE if the window has redrawn the client area background with the class brush, 
FALSE if the window does not redraw the background. The rcPaint element is a pointer to a 


. RECT rectangle data structure, holding the bounds of the smallest rectangle that encloses the 


Uses 
Returns 
See Also 


- Parameters 
hWnd 


IpPaint 
Related Messages 
Example 


update region of the client area. 

Used anytime a program processes WM_PAINT messages. 
HDC, a handle to the window's client area device context. 
EndPaint(), GetDC(), GetWindowDCQ) 


HWND: The window’s handle. 

LPPAINTSTRUCT: A pointer to a PAINTSTRUCT data structure that BeginPaint() will fill. 
WM_PAINT 

This example paints the update region of the client area gray when a WM_PAINT message is 
received. This only occurs if the “Do It!” menu item has been clicked. The simplest way to gener- 


ate a WM_PAINT message is to resize the window, which results in the entire client area being 
the update region. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ; Ps ; 

static BOOL bDoPaint = FALSE ; 

switch (iMessage) . /* process windows messages */ 
. 


case WM_PAINT: 
if (bDoPaint) 
{ 


BeginPaint (hWnd, &ps) ; 
SelectObject (ps.hdc, GetStockObject (LTGRAY_ BRUSH)) ; 
Rectangle (ps.hdc, ps.rcPaint.left, ps.rcPaint.top, 
ps.rcPaint.right, ps.rcPaint.bottom) ; 

EndPaint (hWnd, &ps) ; 

>: , 

else 
ValidateRect (hWnd, NULL) ; 

bDoPaint = FALSE ; 

3 break ; ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ . 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
bDoPaint = TRUE ; 
break ; 
[Other program lines] 
Cuorp gWin2.0 mWin30 mWin3.l 
Purpose Draws a chord segment with the selected pen, and fills the interior with the selected brush. 


Synjax 
Description 


BOOL Chord(HDC ADC, int X/, int Y/, int X2, int Y2, int X3, int Y3, int X4 , int Y4); 

Achord is an elliptical curve, bounded by a line through the ellipse. The elliptical curve is defined 
by the bounding rectangle XJ, Y/ to X2,Y2. The line through the ellipse is defined by X3,Y3 to 
X4,Y4. The currently selected pen and brush for the device context are used to draw the chord’s 
exterior lines and fill the interior. The line segment defined by X3, ¥3 to X4, ¥4 can be outside of 
the bounds of the ellipse. Only the portion within the ellipse will be drawn. 
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Uses This is the filled equivalent to using the Arc() function. 
Returns BOOL. TRUE if ie chord was sues FALSE on error.. = : g @ neric [ele 
See Also Arc(), BeginPaint(), BeetoWiedy Bolt! Quit | 
Parameters: | | 
hDC HDC: The device context handle. : ‘ae 
xl int: The logical X coordinate of the upper left corner of the 

bounding rectangle. 
YI _ int: The logical Y coordinate of the upper left corner of the 

bounding rectangle, 
x2 int: The logical X coordinate of the lower right corner of the 

, bounding rectangle. 

Y2 int: The logical Y coordinate of the lower right corner of the 

bounding rectangle. Figure 11-6. Chord()° 
X3 int: The logical X coordinate of the starting point of the line Example. 

segment of the chord. 
Y3 int: The logical Y coordinate of the starting point of the line segment of the chord. 
x4 _ int: The logical X coordinate of the ending point of the line segment of the chord. 
Y4 int: The logical Ycoordinate of the ending point of the line segment of the chord. 
Example This example, illustrated in Figure 11-6, draws a red chord outline filled with a blue crossed 


interior. The bounding rectangle is also shown for reference. 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 

HPEN hPen ; 

HBRUSH hBrush ; 

switch (iMessage) /* process windows messages */ 


case WM_PAINT: 

\ BeginPaint (hWnd, &ps) ; 

mn SelectObject (ps.hdc, GetStockObject (BLACK_PEN)) ; 

, Rectangle (ps.hdc, 10, 10, 110, 110) ; /* show bounding rect */ 
hPen = CreatePen (PS_SOLID, 4, RGB (255, 0, 0)) ; 


SelectObject (ps.hdc, hPen) ; ‘'/* select a thick red pen */ 
hBrush = CreateHatchBrush (HS_CROSS, RGB (0, 0, 255)) ; © 
SelectObject (ps.hdc, hBrush) ; /* select a blue brush */ 


Chord (ps.hdc, 10, 10, 110, 110, 0, 200, 60, 10) ; 
EndPaint (hWnd, &ps) ; 

DeleteObject (hPen) ; 

DeleteObject (hBrush) ; 

break ; 


[Other program lines] 


CoMmBINERGN Win2.0 mWin3.0  mWin3.1 
Purpose Logically combines two regions into one region. . . 
Syntax . int CombineRgn(HRGN hDestRgn, HRGN hSrcRgn1, HRGN hSrcRgn2, int nCombineMode); 


Description CombineRgn() builds a new region by joining two other regions. The regions do not have to be 
touching. If they are touching, several logical operations can be used to combine areas that over- — 
lap, do not overlap, etc. The destination region must be allocated before the function is started. 

This can be done by creating a region of arbitrary size (using CreateRectRgn() for example). 


444 


11. PAINTING THE SCREEN V 


Uses CombineRgn() can be used many times to build up complex regions made of more basic shapes. 
The combined region can then be used as a mask (clipping region) to limit where painting opera- 
tions are visible. 

Returns int, the result of the function. This can be any of the values listed in Table 11-2. 

poh Meaning 
COMPLEXREGION The new region has overlapping borders. 
ERROR No new region was created. 
NULLREGION The new region is empty. 
_ SIMPLEREGION The new region does not have overlapping borders. 


Table 11-2 Region Types. 


[=[ generic’ [~ [= 


See Also SelectClipRgn(), CreateRectRgn(), CreateEllipticRgn() PDol! gut | 
Parameters = — 
hDestRgn HRGN: A handle to an existing region that will be replaced by the | a ea 


new, combined region. 


. hSrcRgnl HRGN: A handle to an existing region. 


hSrcRgn2 HRGN: A handle to another existing region. Figure 11-7. Combine- 


~-nCombineMode int: Specifies how hSrcRgn1 and hSrcRgn2 are to be combined. Rgn() Example. 
This can be any of the values listed in Table 11-3. 


. Meaning © wh cine, 
RGN_AND Uses the intersection of the two regions (overlapping area). 
RGN_COPY Creates a copy of the region pointed to by hSrcRgn1. . 
RGN_DIFF Copies all of the region pointed to by hSrcRgn1 except for that overlapped by the region pointed to by 
hSrcRgn2. 
RGN_OR ~ Combines the two regions. 
RGN_XOR Combines the two regions, but eliminates the area that overlaps. 
Table 11-3. CombineRgn() Modes. 
Example This example, which is illustrated in Figure 11-7, creates two regions, an elliptical one and a 


rectangular one. The two regions are then combined into one logical region. The combined region 
is used as a clipping region for painting a large gray area. Only the areas within the region are 
painted. Note that the “combined” region still consists of two distinct areas that do not connect. 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ , : 


PAINTSTRUCT ps; wel 

HRGN hRgn1, hRgn2, hRgnComb ; : / 

switch (iMessage) /* process windows messages */ 
c¢ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hRgnt = CreateEllipticRgn (10, 10, 60, 30) ; 
hRgn2 = CreateRectRgn (70, 10, 100, 40) : 
hRgnComb = CreateRectRgn a, 1,2, 2) ;/* tntedat kee: *) 
CombineRgn ChRgnComb, hRgn1, hRgn2, RGN_OR) ; 
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DeleteObject (hRgn1) ; 
DeleteObject ChRgn2) ; 


SelectClipRgn (ps.hdc, hRgnComb) ; 

SelectObject (ps.hdc, GetStockobject (LTGRAY —BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 500) ; 

EndPaint (hWnd, &ps) ; 

DeleteObject ChRgncomb) ; 


break ; 
[Other program lines] 
CopyREcT wWin2.0 mWin30 mWin3.1 
Purpose Copies the coordinates of one rectangle into another. 
Syntax int CopyRect(LPRECT [pDestRect, EERECE lpSourceRect); [= [ generic” [~ [= 
Description RECT data structures hold the coordinates of the upper left Dolt! O a 
and lower right corners of a rectangle. This function copies the 
coordinates from lpSouceRect to lpDestRect. 
Uses Commonly used prior to OffsetRect() or InflateRect(). , qv 
Returns int, the value has no meaning. 
See Also _ OffsetRect(), InflateRect() ———— 
P. arate pr a CopyRect() 
lpDestRect ' LPRECT: A pointer to a RECT data structure that will contain aXe 
the copied coordinates. 
lpSourceRect LPRECT: A pointer to a RECT data structure that contains the source data to copy. 
Example In the example in Figure 11-8, a complex region is created by combining two regions using the 


logical RGN_XOR operation. The two regions are both based on the same rectangular size. In the 
first step, elliptical region hRgnJ is made from the rectangle’s dimensions. A second rectangle is 
created by copying the first, and then offsetting the rectangle’s coordinates to the right 25 logical 
units. The two regions are combined using CombineRgn() and then used as the clipping region. 
Only the areas within the clipping region end up painted when a large, gray rectangle is drawn. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
fe : 


PAINTSTRUCT ps ; 


HRGN . 
RECT 


hRgnt, hRgn2, nEgueomb : 
rRect, rRect2 ; 


switch: inessage) . /* process windows messages */ 
{ . , 


; case WM_PAINT: 

; BeginPaint (hWnd, &ps) ; 
SetRect (&rRecti, 10, 10, 60, 40) ; 
CopyRect (&rRect2, &rRect1) ; 
OffsetRect (&rRect2, 25, 0) ; 
hRgn1 = CreateELlipticRgnindirect (&rRecti) ; 
hRgn2 = CreateRectRgnIndirect (&rRect2) ; 
hRgnComb = CreateRectRgn (1, 1, 2, 2) ie initialize */ 
CombineRgn (hRgnComb, hRgn1, hRgn2, RGN_ XOR) ; 
DeleteObject (hRgn1) ; 
DeleteObject (hRgn2) ; 


SelectClipRgn (ps.hdc, hRgnComb) ; , 
SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 500) ; 
EndPaint ChWnd, &ps) ; 

. DeleteObject (hRgnComb) ; 
break ; 


[Other program lines] _ 
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CreaTBrusHINDIRECT ee mWin20 mWin30 mWin3l 
Purpose Creates a brush from a bitmap or stock brush shape. 
Syntax _ HBRUSH CreateBrushIndirect(LOGBRUSH FAR */pLogBrush); 


Description The LOGBRUSH data type is defined in WINDOWS.H as 


typedef struct tagLOGBRUSH / 
{ 


WORD LbStyle; /* BS_DIBPATTERN, BS_HATCHED, BS_HOLLOW */ 
| ; /* BS_PATTERN, or BS_SOLID */ 

DWORD ibColor; /* DIB_PAL_COLORS, or DIB_RGB_COLORS 

int ibHatch; /* HS_BDIAGONAL, HS_CROSS, HS_DIAGCROSS */ 


/* HS_FDIAGONAL, HS_HORIZONTAL, or HS_VERTICAL */ 
*} LOGBRUSH; : 


typedef LOGBRUSH *PLOGBRUSH; 
typedef LOGBRUSH NEAR *NPLOGBRUSH; 
typedef LOGBRUSH FAR *LPLOGBRUSH; 


typedef LOGBRUSH PATTERN; 


The three data elements of the LOGBRUSH structure are filled to define the brush. Logical 
brushes, like logical fonts, provide a degree of device independence. If an exact match is not 
found with the physical device being used, Windows will approximate the brush. 


Uses Used to create specialized brush patterns for filling regions. 

Returns HBRUSH, a handle to the brush created. Returns NULL on error. - 

See Also SelectObject(), DeieteObject(), CreateHatchBrush(), CreateSolidBrush(), CreatePattern- 
Brush(), UnrealizeObject() 

Parameters 

. lpLogBrush LOGBRUSH FAR *: A pointer to a LOGBRUSH data structure. The elements of the data structure 

are defined as follows: 

lbStyle WORD: The style of the brush to be created, can be any of the ones listed in Table 11-4. 


eecareeX | 


BS | DIBPATTERN The ph will be defined bat a DB (device panes bitmap) 
BS_HATCHED The brush will be a hatched brush based on one of the standard hatch pattems listed in Table 11-6. 
BS_HOLLOW The brush will be hollow(not visible). 

BS_PATTERN The brush will be based on a bitmap. 

BS. SOLID - — Thebrush will be a solid color. 


Table 11-4. Logical Brush Types. 


lbColor _ COLORREF: Specifies the color of the brush for the BS_HATCHED or BS_SOLID styles. Use the 
RGB macro to set a specific color. /bColor is ignored for the BS_HOLLOW or BS_PATTERN style. 
- For the BS_DIBPATTERN aes the loColor aa can have one of the two values listed in 
' Table 11-5. . 


‘DIB_PAL_COLORS TheDIB 00 colors cic based onthe sanaie realized gical an 
DIB_RGB_COLORS The DIB colors are literal RGB values. . 


Table 11-5. Logical Brush Color Types. 
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lbHatch int: For the BS_HATCHED style, lbHatch contains one of the values listed in Table 11-6. 


HS_BDIAGONAL — 45-degree lines climbing from left to right. 
HS_CROSS A horizontal and vertical crosshatch. 
HS_DIAGCROSS ‘A 45-degree crosshatch. 

HS_FDIAGONAL  45-degree lines climbing from right to left. - 
HS_HORIZONTAL Horizontal lines. 
HS VERTICAL Vertical lines. 


Table 11-6. Hatch Brush Patterns. — 


"Ifthe style is BS_SOLID or BS_HOLLOW, lbHatch is ignored. If the style 
is BS_PATTERN, lbHatch contains a handle to a bitmap. If the style is 
BS_DIBPATTERN, /bHatch contains a handle to a DIB bitmap. 


Example This example uses CreateBrushIndirect() twice to create two different 
brushes. (See Figure 11-9.) The first is a hatched brush that uses the 
standard HS_CROSS pattern to paint the top rectangle. The second is a 
custom brush, based on an 8 by 8 bitmap pattern. The bitmap is refer- 
enced with the line y Bona 


[= Igeneric|~ |=" 


Ox 


brush MAP brush. Gx 
rushmap _ BIT rus BaP, Figure 11-9. 
in the program’s .RC resource file. In this case, the bitmap was created CreateBrush 
using the SDKPaint application. Indirect() Example. 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 
PAINTSTRUCT ps ; 
HBRUSH hBrush, hOlLdBrush ; 
= LOGBRUSH LbBrush ; 
HBITMAP hBitmap ; 
switch (iMessage) /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
LbBrush.LbStyle = BS_HATCHED ; 
lbBrush.tbColor = RGB (0, 255, 0) ; 
LbBrush.tbHatch = HS_CROSS ; 
hBrush = CreateBrushIndirect (&lbBrush) ; 
hOldBrush = SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 5, 5, 100, 80) ; 
SelectObject (ps.hdc, hOtdBrush) ; 
DeleteObject ChBrush) ; 

F hBitmap = LoadBitmap (gihInstance, “brushmap"):; 

_lbBrush.lbStyle = BS_PATTERN ; 

LbBrush.lbColor = NULL ; 
tbBrush.lbHatch = hBitmap ; 
hBrush = CreateBrushIndirect (&lbBrush) ; 
hOldBrush = SelectObject (ps.hde, hBrush) ; 
Rectangle (ps.hdc, 5, 100, 100, 180) ; 
SelectObject (ps.hde, hOldBrush) ; 

i DeleteObject ChBrush).; 

DeleteObject (hBitmap) ; 
EndPaint (hWnd, &ps) ; 
break ; 


[Other program lines) 
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aE 
aE ATES ueeice en Win2.0 mWin3.0 mWin3.1 
Purpose Creates an elliptically shaped region. , 
Syntax HRGN CreateEllipticRgn(int X/, int Y/, int X2, int ¥2); 
Description The region is an ellipse, bounded by the rectangle described by the.X, 4 positions of ce upper left ~ 
and lower right corners. 
Uses Used to create clipping regions. 
- Returns HRGN, the handle to the region created. NULL on error. 
See Also SelectObject(), DeleteObject(), SelectClipRgnQ), CreateRect- 
* Regn), CreateElliptic melee 
Parameters 
Xi int: The logical Xcoordinate of the upper left corner of the 
- bounding rectangle. 
YI int: The logical Y coordinate of the upper left corner of the 
bounding rectangle. Figure 11-10. Create 
X2 int: The logical X coordinate of the lower right corner of the EllipticRgn() Example. 
bounding rectangle. . 
y2 int: The logical Y coordinate of the lower right corner of the bounding rectangle. 
Example The example in Figure 11-10 sets a small elliptical clipping region, and then paints a large dent! 


angle with a gray brush. Only the part of the rectangle that falls within the clipping region is 
painted. This results in drawing a filled ellipse. 


- Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParan, LONG lParam) 
{ 


PAINTSTRUCT ps ; 
HRGN hRgn ; 
switch (iMessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hRgn = CreateELlipticRgn (10, 10, 60, 30) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 500) ; 
EndPaint (hWnd, &ps) ; 
DeleteObject ChRgn) ; 


break ; 
[Other program lines] 
CREATEELLIPTICRGNINDIRECT mWin2.0 mWin3.0 m Wind 
Purpose Creates an elliptical region based on the bounding rectangle described in a RECT data structure. 
Syntax HRGN CreateEllipticRgnindirect(LPRECT lpRect); 
Description Identical to CreateEllipticRgnQ), except that a RECT data structure is used to hold the bounding 
rectangle for the ellipse. he ve 

Uses A RECT data structure iswiore: “convenient if you will be doing operations on the rectangle to 

create new regions, The tolling example uses saa to create another region, smaller 
: _ than the first. 
Returns _ HRGN, a handle to the region created. NULL on error. 
See Also CreateEllipticRgn() 


449 


WINDOWS API BIBLE 


ipRect LPRECT: A pointer to a RECT data structure holding the bounding nn oon 
. ‘Fectangle for the ellipse. = oe] 
Example  _—_‘The example shown in Figure 11-11 creates two elliptical regions, 


_ one inside the other. The regions are combined using the logical 
RGN_DIFF operator to create a new region consisting of the parts of 
the larger ellipse that are not in the smaller one. A large area in the 
client area is then grayed, but only the logical region is painted. 


' Figure 11-11, Create- 


EipticRgnIndirect() 
. Example. 

long FAR PASCAL WndProc CHWND. hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . ; 

PAINTSTRUCT ps ; 

HRGN hRgnt, hRgn2, hRgnComb ; 

RECT rRectangle ; 

switch (iMessage) /* process windows messages */ 

{ a 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SetRect (&rRectangle, 30, 30, 100, 80) ; 
hRgni = CreateEllipticRgnindirect (erRectangle) ; 
InflateRect. (&rRectangle, ~10, -10) ; 
hRgn2 = CreateEilipticRgnIndirect (&arRectangle) ; 
hRgnComb = CreateRectRgn (1, 1, 2, 2) 7/* initialize bal A 
CombineRgn (ChRgnComb, hRgnt, hRgn2, RGN DIFF) ; 
DeleteObject ChRgn1) ; 
DeleteObject ChRgn2) ; 


SelectcClipRgn (ps.hdc, hRgnComb) ; 

SelectObject (ps.hde, GetStockobject (LIGRAY_| BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 700): 

EndPaint Chwnd, 8ps) ; 

DeleteObject ChRgnComb) ; 


a break ; 
al il lines] 
CreateHarcuBeuse sm Win. min. win LL 
Purpose Creates a logical brush based ona Saban pattern. 
Syntax . . HBRUSH CreateHatehBrush(int nindex, DWORD erColor); 


Description _This function is used to create brushes with standard patterns. For creating custom brushes, use 
CreateBrushIndirect() or CreatePatternBrush(). 


Uses — i Creating brushes to use for filling rectangles, chords, ellipses, etc. 
Returns  -—-—-«- HBRUSH, a handle tothe brush created. NULL on error. 
._SeeAlso DeepreiieaieaO; CreatePattor Brush, CreateSoldBrush0, UnrealizeObjeetQ) 
Parameters 
| nIndex int: Species the hatch nee This can be any o of the patterns listed in Table re 
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HS. BDIAGONAL 45- ogee i ines aabiak roa left to ‘cbt 


HS_CROSS A horizontal and vertical crosshatch. 
HS_DIAGCROSS A 45-degree crosshatch. | Pegreareemrenspeer 9 
HS_FDIAGONAL —_45-degree lines climbing from right to left. jaa Ly: a 


P 1 
HS HORIZONTAL Horizontal lines. [ Do RY Quit 


~ HS_VERTICAL Vertical lines. Ss 
Table 11-7. Hatch Brush Patterns. 


‘erColor COLORREF: Specifies the color of the hatch lines. Use the RGB macro 
to specify a color. 
Example The example in Figure 11-12 creates a blue diagonal brushandared figure 11-12. 


_ pen and selects both into the device context. The Rectangle() func- CreateHatchBrush() 
tion is then used to draw a filled rectangular region withared border. £xample. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam,’LONG LParam) 
{ : 


PAINTSTRUCT ps ; ae 

HBRUSH ; hBrush ; os 

HPEN hPen ; 

switch (iMessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hBrush = CreateHatchBrush CHS _F DIAGONAL, 
RGBCO, O, 255))d; - 
SelectObject (ps\hdc, hBrush) ; et 
hPen = CreatePen (PS_SOLID, 5, AGB (255, 0, |); 
SelectObject (ps.hdc, hPen) ; er 
“Rectangle (psahdc, 5, 5, 100, 80) ; os 
‘EndPaint (hWnd, &ps) 7. 
BeleteObject chBrush) } 


DeleteDbject- ChPen) ; \ 
; break ; “ ; 
[Other program lines] . 
rs / / ” ; 
CREATEPATTERNBRUSH i034 : eWin2.0 mWin30- BWin3l 
Purpose __ Creates a brush based on a bitmap. - 
Syntax _ HBRUSH CreatePatternBrush(HBITMAP hBitmap); 
Description This is a handy way to create a custom brush for filling objects like rectangles, ellipses, and 
' chords. 
Uses , Used along with LoadBitmap(), CreateBitmap(), CreateBitmapIndirect() or CreateCompa 
ts tibleBitmap(). 
Returns - HBRUSH, the handle of the brush created. NULL on error. 


See Also LoadBitmap(), SelectObject(), DeleteObject(), CreateBrushIndirect(), CreateHatchBrush(), 
oa CreateSolidBrush(), UnrealizeObjectQ) 
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‘Parameters 


i: hBitmap 


Example 


Long FAR PASCAL WndProc CHWND hWnd 


HBITMAP: The handle of the bitmap to use as a brush. This should be 
an 8 by 8 bitmap. If the bitmap is larger, only the upper left, 8 by 8 
pixel area will be used. 


In this case, both a pen and pattern brush are selected into the device 
context before drawing the rectangle. (See Figure 11-13). The custom 
brush pattern is an 8 by 8 pixel bitmap created with the Windows 
SDKPaint application. The program’s .RC resource file contains the 
line 

brushbitmap BITMAP brush. bmp 


Here is the top of the WndProc() function: 


; Dolt! Quit 
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Figure 11-13. 
CreatePattern Brush() 
Example. 


, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
PAINTSTRUCT ps ; 
HBRUSH hBrush ; 
HPEN hPen ; 
HBITMAP hBitmap ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_PAINT: as . 
BeginPaint (hWnd, &ps) ; F 
hBitmap = LoadBitmap (ghInstance, “brushbitmap") ; 
hBrush = CreatePatternBrush (hBitmap) ; 
SelectObject (ps.hdc, hBrush) ; 
hPen = CreatePen (PS_SOLID, 5, RGB (255, 0, 0)) ; 
SelectObject (ps.hdc, hPen) ; 
Rectangle (ps.hdc, 5, 5, 100, 80) ; 
EndPaint (hWnd, &ps) ;. 
DeleteObject (hBitmap) ; 
DeleteObject ChBrush) ; 
DeleteObject (hPen) > © 
4 . break ; 
[Other program lines] 
CREATEPEN BWin2.0 |Win3d.0 mWind.! 
Purpose Creates a logical pen. a a 
Syntax HPEN CreatePen(int nPenSlyle, int nWidth, DWORD crColor); ae 
Description The only two stock pens are a black line and a white line, both one 
_ pixel thick. Use CreatePen() to create all other line types. 
Uses Creating a pen prior to selecting the pen into the device context. _ 
Returns HPEN, the handle of the pen produced. 
See Also CreatePenIndirect(), SelectObject(), DeleteObject() 
Parameters nme 
nPenStyle int: The pen style. This can be either PS_SOLID, PS_DASH, PS_DOT, Figure J1-14. | 
PS_DASHDOT, PS_DASHDOTDOT, PS_NULL, or PS_INSIDEFRAME. CreatePen() Example. 
The latter is used to draw the border of all objects other than poly- 
gons and polylines. 
nWidth int: The pen’s width in logical units. 
crColor COLORREF: The color of the line. Use the RGB macro to specify an exact color. 
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Example — ~The rectangle, shown in Figure 11-14, is drawn with a red pen, created five units wide. Because no 
brush was selected, the default white brush is used to fill the rectangle. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps >; 

HPEN hPen ; 

switch (CiMessage) /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hPen = CreatePen (PS_SOLID, 5, RGB (255, 0, 0)) ; 
SelectObject (ps.hdc, hPen) ; 
Rectangle (ps.hdc, 5, 5, 100, 80) ; 
EndPaint (hWnd, &ps) ; 
DeleteObject (hPen) ; 


break ; 
[Other program lines] 
CREATEPENINDIRECT gWin2.0 mWin3.0 mWin3.1 
Purpose Creates a logical pen based on LOGPEN data. 
Syntax HPEN CreatePenIndirect(LOGPEN FAR * lpLogPen); 
Description This function is identical to CreatePen(), except the data for the pen is passed in a LOGPEN data 


structure rather than as parameters. LOGPEN is defined in WINDOWS.H as follows: 
typedef struct tagLOGPEN 
{ 


WORD LopnStyle; ; , 
_ POINT LopnWidth; Len 
DWORD LopnColor; Bee 
} LOGPEN; pee 
typedef LOGPEN ; *PLOGPEN; ee 
typedef LOGPEN NEAR *NPLOGPEN; Let 
typedef LOGPEN FAR *LPLOGPEN; ‘“ cs 
: : ae Do It! "Quit 
Uses More convenient than CreatePen() if you havea number ofsimilarpens § 
to create. 
Returns HPEN, a handle to the pen created. NULL on error. 
See Also CreatePen(), SelectObject(), DeleteObject() 
Parameters 
lpLogPen .  LOGPEN FAR *: A pointer to a LOGPEN data structure. The elements 
- of the data structure are as follows. . cieiaieidmiigaciaieal 
lopnStyle WORD: The pen style. This can be either PS_SOLID, PS_ DASH, Figure 11-15. Create- 


PS_DOT, PS_DASHDOT, PS_DASHDOTDOT, PS_NULL, or PS_IN- Pendndirect() 
SIDEFRAME. The latter is used for drawing the border of all objects “ample. 
other than polygons and polylines. 


lopnWidth POINT: A POINT structure. The x element of the POINT structure defines the pen’s width. Only 
the x element of the structure is used. 

lopnColor COLORREF: The 32-bit color value to use for the pen. Use the RGB macro to specify a color. 

Example Here a polygon is drawn, see Figure 11-15, using a pen created with CreatePenIndirect(). 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{t : 


PAINTSTRUCT ps ; 
HPEN hPen ; 
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LOGREN lp; 


POINT pPenWidth ; 
' POINT pArray C] = (10, 100, 15, 5, 50, 50, 90, 0, 60, 110} ; 
switch CiMessage) | /* process windows messages */ 


case WM_PAINT: 

BeginPaint (hWnd, &ps) ; 

pPenWidth.x = 2; 

tp.lopnStyle = PS_DASH ; 

Lp.lopnWidth = pPenWidth ; 

lp. lopnCotor = RGB (0, 40, 50) ; 

; hPen = CreatePenIndirect (&lp) ; 

q SelectObject (ps.hdc, hPen) ; 

Polygon (ps.hdc, pArray, 5) ; 

EndPaint (hWnd, &ps) ; 

DeleteObject ChPen) ; 


break ; 
[Other program lines]. 
CrEATEPOLYGONRGN Win2.0 mWin30 Win3.1 
Purpose . Creates an arbitrary, shaped polygonal region. ° 
Syntax | HRGN CreatePolygonRgn(LPPOINT /pPoints, int nCount, int nPolyFillMode): 
Description _ This function is ideal for creating clipping modes that have complex shapes. Any number of points 
". can be specified. SABA eT 
Uses | Complex clipping modes. T generic aa [-— 
Returns __’ HRGN, a handle to the region created. NULL on error. | Dolt! Quit | 
See Also  —CreatePolyPolygonRgn() eee 
Parameters 7 fo | | 
~IpPoints ae ° LPPOINT: A pointer to an array of POINT structures contain- 
Pees ing at least nCount points. 
nCount’  - int: The nushber of points to use in drawing the polygon. 


nPolyFillMode int: The polygon filling mode. This is important only ifthelines Figure 11-16. CreatePoly- 
es , ’ of the polygon /cross each other, creating areas. The mode can gonRgn(, ) Example. 
- be either of the two modes listed in Table 11-8. 


ALTERNATE~ . The GDI ils in areas between sides 182, sides 384, etc. 
WINDING ——___ The GDI fills in the complete area defined by the outermost ines. 


. Table 11-8. Polygon Filling Modes. 


See GetPolyFillMode() or SetPolyFillMode() for more details on the polygon filling modes. 
Example Here a five sided polygon, see Figure 11-16, is used as a clipping region. 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
; PAINTSTRUCT ps ; . 


HRGN : hRgn ; 
POINT pArray C5]°= “C10, 10, 50, 40, 90, 20, 60, 0, 40, 20) ; 
switch. CiMessage) ec ae 7 ‘ /* process windows messages */ 


nl meee oS 


case we PAINT: 
: BeginPaint ChWnd, &ps) ; 
hRgn = CreatePolygonRgn (pArray, 5, WINDING) ; 
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., 2. 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockobject CLTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 0, 0, 500, 500) ; . /* paint gray */ — 
EndPaint. ChWad, &ps) ; a 
Deletedbject ChRgn) ¢ — , 


\ ; break ; 
[Other program tines]. 
CREATEPOLYPOLYGONRGN OWin2.0 mWin30 mWin3.1 
Purpose Creates a region composed of multiple sane in a single function call. 
Syntax HRGN CreatePolyPolygonRgn(LPPOINT lpPoints, LPINT pens: int nCount, int 
nPolyFillMode); 


Description This function can save time in making and combining regions i providing the ability tocreatea — 
region of any complexity in a single function call. This is accomplished by passing two arrays to 
the function, an array of all of the points, and a second array containing an array of integers. The 

. integer array defines how the points are to be grouped. For example, the first four points might 
define the first shape, the second six the second shape, etc. . 


Uses | Creating complex clipping regions without having to combine multiple small regions. The indi- 
. vidual regions defined in the array of points do not have to be touching. 
Returns | HRGN, a handle to the region created. NULL on error. : _ — 
“SeeAlso --—-—_CreatePolygonRgn(), CombineRgn() FL generic [= [= 
Parameters ms 
lpPoints : LPPOINT: A pointer to an array of POINT structures containing the 


location of every point in every polygon that will be defined. The 
points must be sorted so that all of the points defining the first poly- 
gon are together, followed by the points defining the second poly- 
; gon, ete. 
lpPolyCounts ___. LPINT: A pointer to an array of integers. The elements of the array 
describe how many points belong to each of the polygons. . 
nCount _ int; The number of integers in the /pPolyCounts array. This is also Figure 11-17. Create- 
the number of polygons that will be defined. PolyPolygonRgn({) ~ 
nPolyFillMode —_ int: The polygon filling mode. This is important only if the lines of 4vameple. 
sO the polygon cross each other, creating areas. The mode can be ei- 
ther of the modes listed in Table 11-9. 


eaten EEE I let aewtecty., Syne” nos Begg TR 
ALTERNATE The DI fills in areas between sides 1 182, sides 384, etc. 
WINDING The GD! fills in the complete area defined by the outermost lines. 


‘Table 11-9. Polson sid Modes. 


Example The clipping region shown in Figure 11-17 is created by defining a triangular and a four-sided 
polygon in the same call to CreatePolyPolygonRgn(). 


long FAR PASCAL WindProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : = 


PAINTSTRUCT ps; 

HRGN ' hRgn ¢ 

POINT pArray (72 = (10, 10, 50, 40, 90, 20, 60, 0, 80, 80, 
ac 100, 110, 120, 30) ; 


int nPolyCount. C1= (3, 4); 
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switch (iMessage) 


/* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) 
hRgn = CreatePolyPolygonRgn (pArray, Se alt 2, 
WINDING) ; 
SelectClipRgn (ps. hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockobject CLTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 0, 0, 500, 500) ; /* paint gray. i 
’ EndPaint (hWnd, &ps) ; 
PeleteObject (hRgn) ; 


break ; 
[Other program lines] 
CREATERECTREGN | Win2.0 @Win3.0 mWin3.1 
Purpose . Creates a rectangular region. oe 
Syntax HRGN CreateRectRgn(int X/, int Y/, int X2, int Y?); 
Description The region created is a rectangle, bounded by the X/,Y/ at the upper left and.X2,¥2 at the lower - 
right. 
Uses Used to create clipping regions or regions to be filled. 
Returns ~ HRGN, the handle to the region created. NULL on error. 
See Also saesonienO, DeleteObject(), SelectClipRgn(), FillRgn() 
Parameters 
x! int: The logical X coordinate of the upper left « corner of the 
rectangle. 
Y1 int: The logical Y coordinate of the upper left corner of the 
rectangle. 
X2 int: The logical X coordinate of the lower right corner of the 
rectangle. 
Y2 int: The logical Y coordinate of the lower right corner of the fH. slate a 
rectangle. Figure 11-18. Create- 
Example This example creates a rectangular region, and uses itasaclip- RectRgn() Example. 


ping region. When a much larger rectangle is drawn, only the 
part within the region ends up visible. (See Figure 11-18.) 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
PAINTSTRUCT ps ; 
HRGN hRgn ; 
switch (iMessage) /* process windows messages */ 
{ « . 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hRgn = CreateRectRgn-(10,'10, 90, 70) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
Rectangle (ps.hdc,'5, 5, 500, 500) ;/* paint gray */ 
EndPaint (hWnd, &ps) ; 
pelereabsect SMR 
break ; 
[Other program lines] 
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CREATERECTRGNINDIRECT Win2.0 mWin30 mWin31 

Purpose Creates a rectangular region based on the data in a RECT data —— 
structure. ee  —.. 

Syntax HRGN CreateRectRgnIndirect(LPRECT [pRect); ion generi fr fae 

Description This is identical to CreateRectRgn(), except the rectangle data 
is passed as the elements of a RECT data structure. ‘ 

Uses Convenient if the rectangle data will be manipulated. The fol- 


lowing example shows the RECT data being used to create a 
new region, offset from the first. 


Keturns HRGN, a handle to the region created. NULL on error. 

See Also CreateRectRgn() 

Parameters . 

lpRect : LPRECT: A pointer to a RECT data structure holding the di- 
_ mensions of the rectangle. 

Example This example creates two rectangular regions, one offset from 


the other. The regions are combined with the logical Figure 11-19. CreateRect- 
RGN_XOR operation. When the entire area is grayed (see Fig- RgnIndirect() Example. 
ure 11-19), only the parts of the regions not overlapping end up 

painted. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ , 


PAINTSTRUCT ps ; 
HRGN hRgni, hRgn2, hRgnComb ; 
RECT rRectangle1, rRectangle2 ; 


switch (iMessage) /* process windows messages */ 
{ F 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 

SetRect (&rRectangle1, 30, 30, 60, 80) ; 
hRgn1 = CreateRectRgniIndirect (&rRectangle1) ; 
CopyRect (&rRectangle2, &rRectangleil) ; 
OffsetRect (&rRectangle2, 20, 20) ; 
hRgn2 = CreateRectRgnIndirect (&rRectangle2) ; 
hRgnComb = CreateRectRgn (1, 1, 2, 2) ;/* initialize */ 
CombineRgn ChRgnComb, hRgni, hRgn2, RGN_XOR) ; 
DeleteObject ChRgn1) ; 
DeleteObject ChRgn2) ; 


SelectClipRgn (ps.hdc, hRgnComb) ; 

SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 500) ; 

EndPaint (hWnd, &ps) ; ” 

DeleteObject ChRgnComb) ; 


break ; 
[Other program lines] 
CrEATEROUNDRECTRGN OWin2.0 mWin3.0 mWin31 
Purpose Creates a rectangular region with rounded corners. . 
Syntax HRGN CreateRoundRectRgn(int X/, int Y/, int X2, int Y2, int X3, int Y3); | 
Description The region created is a rectangle, bounded byX/, Y/ at the upper left and X2, Y2 at the lower right. 


X3 and ¥3 provide the width and height of the ellipses used to round the corners. 
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uses = .. Used tocreate clipping regions. » 

Returns _ HRGN, the handle to the region created. NULL on error. . foal gen mF Pan 

See Also SelectObject(), DeleteObject(), SelectClipR  PRRRUS arbateace a ia re 
| ject(), ject(), pRen() TP Do lt! Quit : 

Parameters — 

XI . int: The logical X coordinate of the upper left corner of the 

bounding rectangle. 

Yl ' int: The logical Y coordinate of the upper left corner of the 

oe ae ao bounding rectangle. cele o 

Xe int: The logical X coordinate of the lower right corner of the | See 

; bounding rectangle. 

¥2 int: The logical Y coordinate of the lower right corner of the Figure 11-20. Create- 

aes . bounding rectangle. RoundRectRgn() Example: 

XS ' int: The logical width of the ellipse used to round the corners. 

¥3 ‘ze int: The logical height of the ellipse used to round the corners. 

Example This example creates a rectangular region with rounded corners and uses it as a clipping region. 


When a much larger rectangle is drawn with a gray brush, only the interior of the region ends up 
tea painted, as shown in Figure 11-20. 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LPdram) 
{ 


PAINTSTRUCT ps ; 

HRGN hRgn ; 

switch (iMessage) /*® process windows messages */ 
{ i 


case WM_PAINT: f 
BeginPaint (hWnd, &ps) ; 
hRgn = CreateRoundRectRgn (10, 10, 90, 70, 20, 20) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 500) ;/* paint gray */ : 
EndPaint Chwnd, &ps) ; Be 
DeleteObject (hRgn) ; 


‘ : . ; break ; 

[Other program lines] 
CreaTESoLIpBRusH _ | @Win20 mWin30 wWin3l 
Purpose | Creates a brush with a solid color. ae a 
Syntax. HBRUSH CreateSolidBrush(DWORD crColor); |—generic|~ |+. 
Description CreateSolidBrush() allows you to create asolid color brush for , 


Do it! Quit { 


filling areas. Before an object like a-rectangle or ellipse can 
have its interior painted, the program must select a brush of 
the desired color into the device context using SelectObject(). 
~ Call DeleteObject() to free the created brush from memory af- 


. ie ter it is used. 

Uses Solid color brushes. Use CreateHatchBrush(), CreatePattern- Figure 11-21. CreateSolid- 
Brush(), and CreateBrushIndirect() to create pattern brushes. Brush() Example. 

Returns HBRUSH, a handle for the brush created. NULL on error. 

See Also. SelectObject(), DeleteObject(), CreateHatchBrush(), CreatePatternBrush(), CreateBrushin- 


direct(), Unrealize Object() . 
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Parameters 


crColor DWORD: The 32-bit color value to use for the brush color. Use the RGB: macro to siacity this 
value. 
Example This example creates a blue/red brush and uses it to fill a rectangle, as shown in Figure 11-21. The 


brush is deleted immediately after the rectangle is painted. i; 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
£ 


PAINTSTRUCT ps ; 

HBRUSH hBrush ; 

switch (iMessage) /* process windows messages */ 
t : 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hBrush = CreateSolidBrush (RGB (10, 0, 50)) ; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 10, 10, 90, 40) ; 
EndPaint (hWnd, &ps) ; 
DeleteObject (hBrush) ; 


break ; 
[Other program lines] 
DELETEOBJECT BWin2.0 wWin3d0 mWin3.1 
Purpose Removes pens, brushes, fonts, bitmaps, regions, and palettes from memory. ° 
Syntax BOOL DeleteObject(HANDLE hObject); 
Description GDI objects must be deleted to free the memory they occupy. Otherwise, they will continue to 


exist in memory after the program exits, Use DeleteObject() to free the memory and eliminate 
the object. Do not delete stock objects (obtained with GetStockObject()). Ifa bitmap is used to 
create a brush, you will have to delete the brush and the bitmap separately. Do not attempt to 
: delete an object that is selected to a device context. Either delete the object after the device 
context is released (after ReleaseDC() or EndPaint() is called), or displace the object out of the — 
device context by selecting another object of the same type, such as a stock object. 
Uses Generally used immediately after the object is used. Some programs create a series of GDI ob- 
jects when the program starts (WM_CREATE), and then delete them all right before the program 
exits (WM_DESTROY). 


Returns BOOL. TRUE if the object was deleted, FALSE on error. Normally, a FALSE return value means 
‘ that, the handle was not valid. 

See Also CreatePen(), CreateSolidBrush(), CreateRectRgn(), LoadBitmap(), 

Parameters : 

hObject HANDLE: The handle of the pen, bitmap, brush, font, region, or palette to be deleted. 

Example The previous example under CreateSolidBrush() shows a typical cycle of creating a brush, ai 


it, and then deleting it. Also see the discussion at the beginning of this chapter. 


DrawF ocusREctT . OWin20 mWin30 mWin3l 

Purpose Draws or removes a dashed line around a rectangle. 

Syntax void DrawFocusRect(HDC hDC, LPRECT lpRect); 

Description The dashed line is drawn with the XOR style, so drawing the focus rectangle a second time at the - 
same location erases the line. 


Uses §—sC To highlight an area temporarily. 
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Returns No returned value (void). 

See Also ~ Rectangle(), InflateRect() 

Parameters 

hDC HDC: The device context handle. 

lpRect LPRECT: A pointer toa RECT structure holding the size of the 
rectangle to paint. 

Example This example creates a pseudo button, shown in Figure 11-22. 


The button background and text are created with RoundRect() famu= 
and DrawText(). The exterior is outlined in a dashed line, or Figure 11-22. Draw- 

- has the dashed line removed, when the user clicks the “Do It!” FocusRect() Example. 
menu item. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . ; 


PAINTSTRUCT ps; 

HBRUSH hBrush ; 

static RECT rRect ; 

HDC hDC ; 

switch (iMessage) : /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hBrush = CreateSolidBrush (RGB (120, 120, 120)) ; 
SelectObject (ps.hdc, hBrush) ; 
SetRect (&rRect, 10, 10, 90, 40) ; 
RoundRect (ps.hdc, 10, 10, 90, 40, 10, 10) ; 
SetBkMode (ps.hdc, TRANSPARENT) ; 
SetTextColor (ps.hdc, RGB (255, 255, 255)) ; 
DrawText (ps.hdc, "Fake Button", 11, &rRect, 
DT_CENTER | DT aVEENTER | DT_SINGLELINE) ; 

EndPaint (hWnd, &ps) ; 
DeleteObject (hBrush) ; 
break ; © 

‘ case. WM_ COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
brawFocusRect (hDC, &rRect) ; 
ReleaseDC (hWnd, hDC) ; 


break ; ‘ 
[Other program lines] “~s 
ELLIPSE mWin2.0 mWin3.0 mWin3.1 
Purpose Draws an ellipse. 
Syntax — BOOL Ellipse(HDC ADC, int X/, int Y/, int X2, int ¥2); 
Description The ellipse is drawn with the currently selected pen and filled with the current brush. 
Uses . ‘A circle can be drawn by defining the bounding rectangle to be a square. 
Returns | - BOOL. TRUE if the ellipse was drawn, FALSE on error. 
See Also Rectangle() 
Parameters ; oe. 
xl int: The logical X coordinate of the upper left corner of the bounding rectangle. - 
Yl int: The logical Y coordinate of the upper left corner of the bounding rectangle. 
Xa int: The logical X coordinate of the lower right corner of the bounding rectangle. 
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int: The logical ¥ coordinate of the lower right corner of the — peppreereenmeeeenseenesenpeeeerasenn 
bounding rectangle. . : Tp ger ui “Sefer ee 
The example shown in Figure 11-23 draws two overlapping el- {Dott Quit 
lipses in the window’s client area. Note that the specification ase 7 

of the TRANSPARENT drawing style allows both of the ellipse J 
lines to be visible in the overlapping region. This does not af- & 

fect the hatched brush pattern. Orly one brush pattern is vis- Figure 11-23. Ellipse() 
ible in the overlapping region. Only lines and text are affected Example. 

by the setting of TRANSPARENT or OPAQUE drawing modes. 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ car 


PAINTSTRUCT ps ; 

HBRUSH hBrush ; 

HPEN hPen ; 

switch CiMessage) /* process windows messages */ 
P ; 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; ’ 
hBrush = CreateHatchBrush CHS _DIAGCROSS, 
RGB (120, 0, 120)) ; 
SelectObject (ps.hdc, hBrush) ; 
hPen = CreatePen (PS_SOLID, 3, RGB (10, 50, 255)) ; 
SelectObject (ps.hdc, hPen) ; 
SetBkMode (ps.hdc, TRANSPARENT) ; 
Ellipse (ps.hdc, 10, 10, 90, 40) ; 
Ellipse (ps.hdc, 62, 10, 142, 40) ; 
EndPaint ChWnd, &ps) ; 
DeleteObject (hPen) ; 
DeleteObject (hBrush) ; 
break ; 


[Other program lines] 


ENDPAINT 
Purpose 
Syntax 
Description 


Uses 
Returns 
See Also 


Parameters 
hWnd 


lpPaint 


Related Messages 
Example 


eWin2.0 gWin30 B8Win3.) 
Ends the painting cycle started by BeginPaint(). 
void EndPaint(HWND hWnd, LPPAINTSTRUCT IpPaint); 


When processing WM_PAINT messages, BeginPaint() is used to get the device context and load 
the PAINTSTRUCT data. EndPaint() is used at the end of the painting cycle to release the device 
context. Use ReleaseDC() to free a device context created with GetDC(), for doing output outside 
of the WM_PAINT processing section of the program. EndPaint() will restore a caret if the caret 
was hidden by a call to BeginPaint(). 

Client area updates while processing WM_PAINT messages. 

No returned value (void). 


BeginPaint(), ReleaseDC(), GetDCQ 


HWND: The handle of the window to be repainted. 


LPPAINTSTRUCT: A pointer to a PAINTSTRUCT data structure that was used by the Begin- 
Paint() function. See the BeginPaint() function description for the structure definition. 


WM_PAINT 


_ The previous example under Ellipse() shows a typical cycle of using BeginPaint(), GDI functions, 


and EndPaint() while processing a WM_PAINT message. 
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EnumOsseEcts 3  mWin.0 mWin3.0 ) mWindl | 


. Purpose ~~ Enumerates all of the physical pens or brushes available on a device context. 
Syntax _. int EnumObjects(HDC ADC, int nObjectType, FARPROC lpObjectFunct, LPSTR ipData); 
_ Description EnumObjects() calls a callback function for every pen or brush possible on the device context. 
The callback function can store this ‘ata for later use. ; 
Uses ; Determines the number and type of physical pensor brushes that can be attached to the device 


context. You can use the data to create one or more logical pens that match the exact physical 
pens/brushes available. Logical pens/brushes that do not have an exact match will end up using 
the closest physical item. 


Returns int, the last value returned by the callback function. Normally, not used. 


See Also _ EnumFonts() | ; 

_ Parameters ; a . [SST generic 
hDC HDC: The device context handle. ee 

. nNObjectType int: The type of object to enumerate. This can be either Style = 8, Width = 0, Color = FFFFO000 
IpObjectFunct FARPROC: The procedure-instance address of the callback A O; Width 20, Coter'= Erreuaed 


function. This function name must be listed in the EXPORTS Style = 0. Width = 0. Color = 
section of the program’s .DEF definition file. The procedure- Figure 11-24. Brennen ) 
instance address should be obtained with MakeProc- Example. 


. Instance(). 
lpData LPSTR: A pointer to the data structure that the callback function should use. Normally the call- 
, back function will reallocate this memory block to enlarge it every time a new piece of data i isto | 
be stored. 
Example This program lists all of the pens possible with the client area’s device context, as shown in 


- Figure 11-24. The list goes past the end of the screen. Note that a width of zero draws a one pixel 
wide line regardless of the mapping mode. 
The program's header file includes the definition of the ENUMER data type used in the enu- 
meration of the pens. The enumeration function prototype is also in the header file. 
/* generic.h */ ; . os 
Adefine IOM_DOIT 1 /* menu item id values */ 
' Adefine IDM_QUIT 2 , 


/* definitions */ 
typedef struct 
{ 


GLOBALHANDLE _. hGMem ; 


eal int = nCount ; 
} ENUMER is . 

/* global variables */ 

int ghinstance ; 


char gszAppName CJ) = "generic" 


/* function prototypes */ 
long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 
BOOL FAR PASCAL PenEnumFunc Cchar FAR R *lpLogobject, 
ENUMER FAR *enumer).; 


The enumeration function name must also be listed in the EXPORTS section of the program’s 
_ DEF definition file. 


tong. FAR PASCAL undProc CHWND hwnd, unsigned iMessage, WORD wParam, LONG lParam? 
C 


“] 
static \ FARPROC i eenaabeoe : 
static ENUMER ~\ enumer ; 


‘ 
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LPLOGPEN LpLogPen ; 

char . FAR *fp; 

HDC ; one ; 

int : 

char we C128] ; 

switch (iMessage) . _ /* process windows messages */ 
{ 


case WM_CREATE: 
tpfnEnumProc = 
MakeProcInstance (PenEnumFunc, ghInstance) ; 
break ; 
case WM _ COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
if Cenumer.hGMem) /* +f not first time tried */ 
GlobalFree Cenumer.hGMem) ; 
/* Tatelalize storage area */ 
enumer .hGMem = GlobalAlloc (GMEM_MOVEABLE | 
GMEM_ZEROINIT, 1L) ; 
enumer.nCount = 0 ; 
hOC = GetDC ChWnd) ; 
/* Let Windows cun callback func. «/ 
EnumObjects (hDC,.0BJ —PER, LpfnEnumProc, 
CLPSTR) Senumer) ; 
LpLogPen = (LPLOGPEN) GlobalLock Cenumer.hGMem) ; 
TextOut (hdc, 10, 10, cBuf, wsprintf (cBuf, 
“Enum0Objects() found 4a:", 
enumer.nCount)) ; 
fp = (char far *) LpLoaPen : 
for Ci = 0; i < enumer.nCcunt ; i++) 
{ /* display each pen found “f 
TextOut C(hDC, 15, 30 + (15 * 1), 
cBuf, wsprintt (cBuf, 
“Style = %d, Width = 4d, Color = Z0LX", 
LpLogPen->LlopnStyle, : 
LpLogPen->LlopnWidth, 
lpLogPen->lopnColor )) ; 
fp += sizeof (LOGPEN) ; 
= lpLogPen = (LPLOGPEN) fp ; 
} 
GlobalUnlock Cenumer.hGMem) ; /* unlock memory af 
ReleaseDC (hWnd, hDC) ; 
break ; : 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; , 
break ; 
} a 
break ; 
case WM_ DESTROY: stop application x/ 
GlobalFree (enumer. hGMem) ; /* release all memory / 
FreeProciInstance CipfnenuaProe) 7 
PostQuitMessage (0) ; 
break ; 
defaults: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, (lParam) ; 
} ee 
return COL) ; 


BOOL FAR PASCAL PenEnumFunc (char FAR ie cae a ENUMER FAR *enumer) 
{ 


LPLOGPEN - LpLogPen ; 
static -. °. int i; . | ees 
char . = FAR ‘kEp 5 : 


if (1GLobaLReAt Loc Canumec>ucnea: 
CDWORD) sizeof CLOGPEN) *. (enumer->nCount + ie 
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GMEM_MOVEABLE) ) 
return (0) ; /* quit if can't make room */ 


ipuogren = (LPLOGPEN) GlobalLock Cenumer->hGMem) ; 
= (char far *) LpLogPen ; 
Ha += enumer->nCount * sizeof (LOGPEN) ; 


for (i =0; i < sizeof (LOGPEN); i++) /* copy pen to buffer */ 
efpt+ = *lpLogobject++ 3 ‘ 

GlobalUntock Cenumer->hGMem) ; /* unlock the memory area */ 

enumer->nCountt+ ; /* keep track of how many */ 

return (1) ; 
} . 
Equa.REct Win2.0 mWin3.0 mWin3.1 
Purpose Checks whether two rectangles are equal. . EE aeS SRT OPTED a7 
Syntax BOOL EqualRect(LPRECT lpRect!, LPRECT IpRect2); j= (generic | * |: : 
Uses Normally used to avoid unnecessary painting. 1 Do tt " Quit 
Returns BOOL. TRUE if the rectangles are equal, FALSE if not. f 
See Also EqualRgn() 

Parameters zz a 

lpRect1 LPRECT: A pointer to the first RECT data structure. Figure 1 1 6p 5 EqualRect() 
lpRect2 LPRECT: A pointer to the second RECT data structure. Example after Several 
Example This example creates two rectangles every time a WM_PAINT WM_PAINT Messages. 


“message is received. If the two are not equal, both are drawn. 
The second rectangle is offset to the right every time a WM ~PAINT message is processed. (See 
Figure 11-25.) 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
C ! 


PAINTSTRUCT ps; 

RECT rRect1, rRect2 ; 

static ; int nPaintCount = 0’; 

switch CiMessage) _/* process windows messages */ 
{ 


case WM_PAINT: 

BeginPaint (hWnd, &ps) ; 

SetRect (&rRecti, 10, 10, 60, 30) ; 

SetRect (&rRect2, 10 + na tnccount, 10, 
60 + nPaintCountt+, 30) ; 

SelectObject (ps.hdc, GetStockObject (BLACK_PEN)) ; : 

Rectangle (ps.hdc, PRectL Leth, rRecti.top, rRecti.right, 
rRect1.bottom) ; 

if C'EqualRect (&rRect1, &rRect2)) 
Rectangle (ps. hdc, rRect2. left, rRect2. top, 

rRect2.right, rRect2.bottom) ; 
EndPaint Chund, &ps) ; 


break ; : . ~ 
[Other program lines] 
EquatRcn _ : ; Win2.0 eWin3.0 mWin3.1 
Purpose . \Checks to see if two regions are equally sized. 
Syntax | - BOOL EqualRgn(HRGN hSrcRgnI, HRGN hSrcRgn2); 
Uses If, two regions are equally sized, there is no reason to combine them. 
Returns -BOOL. TRUE if the regions are equal, FALSE if not. 
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See Also EqualRect() 

Parameters 

hSrcRgnI HRGN: The first region’s handle. 

hSrcRgn2  ——sHIRGN: The second region’s handle. 

Example — Here two elliptical regions are created. If they are not identi- 


cal, they are combined to create a clipping region. Every time a 
WM_PAINT message is received, one of the bounding rect- 


angles is offset to the right. one logical unit (pixel). (See Figure Figure 11-26. EqualRgn() 
11-26.) . Example after Several 


WM_PAINT Messages. 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps; 

HRGN hRgn1, hRgn2, hRgnComb ; 

static int nPaintCount = 0; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hRgn1 = CreateELlipticrgn (10, 10, 60, 30) ; 
hRgn2 = CreateELlipticRgn (10 + nPaintCount, 10, 
60 + nPaintCount++, 30) ; 
hRgnComb = CreateRectRgn (1, 1, 2, 2) 7 
if C!EqualRgn ChRgn1, hRgn2)) 
CombineRgn ChRgnComb, hRgni, hRgn2, RGN_OR) ; 
else 
CombineRgn (hRgnComb, hRgn1, NULL, RGN_COPY) ; 
DeleteObject (hRgnt) ; 
DeleteObject (hRgn2) ; 


SelectClipRgn (ps.hdc, iWenGoabys 
SelectObject (ps.hdc, GetStockObject CLTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 500) ; 
EndPaint ChWnd, &ps) ; 
DeleteObject (hRgnComb) ; 


: break ; 
[Other program lines] 
EXxcLuDECLIPRECT mWin2.0 wWind0 mWin3l 
Purpose Removes a rectangular area from a clipping region. i a 
Syntax int ExcludeClipRect(HDC hDC, int XJ, int Y/, int X2, int Y2); 
Description Hollow clipping regions can be created by first creating a clipping region, and then excluding a 
central portion with this function. 
Uses Creating clipping regions that limit where on the device context painting will occur. 
Returns int, the type of region created. This can be any of the types listed in Table 11- 10. 


COMPLEXREGION The new region has pieiening porter. 


ERROR ~ No new region was created. 
NULLREGION The new region is empty. . 
SIMPLEREGION The new region does not have overlapping borders. 


Table 11-10. Region Types. 
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See Also _ ExcludeUpdateRgn(), SelectClipRgn() : (i[qenerie|>1- 
-Parameters 


i Dolt! Quit —- 


ADC _ HDC:. The device context handle. 
AP ~ int: The logical X coordinate of the upper left corner of the bounding 
. _o* + yectangle. 
YI int: The logical Y coordinate of the upper left corner of the bounding 
‘rectangle. | . . 
Xo int: The logical X coordinate of the lower right corner of the bounding 
rectangle. Figure 11-27. 
Y2 ‘ints The logical Y coordinate of the lower right corner of the bounding ExcludeClipRect() 
rectangle. Example. — 
Example As shown in Figure 11-27, a rectangular clipping region is created. The center of the clipping 


region is eliminated using ExcludeClipRect(). A large area is painted with a gray brush, but only 
the clipping area is affected. 


tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WCRD wParam, LONG lParam) 
rd 


PAINTSTRUCT ps; 
HRGN hRgn ; 
switch (iMessage) ‘ ' 7* process windows messages */ 


case WM_PAINT: : 
. BeginPaint ChWnd, &ps) ; 

hRgn = CreateRectRgn (10, 10, 100, 100) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
ExcludeClipRect (ps.hdc, 30, 30, 80, 80) ; 
SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 0, 0, 500, 500) ; /* paint area */ 
EndPaint (hWnd, &ps) ; 
DeleteObject (hRgn) ; 


break ; 
[Other program lines] 
ExcLupEUPDATERGN eWin2.0 wWin3.0 mWin3.1 
Purpose Prevents drawing in invalid areas of the client area. 
Syntax —-—sint ExeludeUpdateRgn(HDC ADC, HWND hWnd); . 
Description  —‘If program logic outside of the processing of WM_PAINT messages causes parts of the client area 


' to become invalid (need repainting), these areas will be repainted on the next WM_PAINT cycle. 
ExcludeUpdateRgn() keeps GDI operations from painting in the invalidated areas. 


Uses Commonly used with programs that scroll the window's client area. 
Returns int, the type of region created. This can be any of the types listed in Table 11-11. 


COMPLEXREGION The new region has overlapping borders. 


ERROR _ No new region was created. 

NULLREGION — _ The new region is empty. 

SIMPLEREGION ~The new region does not have overlapping borders. 
Table 11-11. Region Types. . 
See Also -  ExcludeClipRect() 
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Parameters -_ 

hDC HDC; The device context handle for the window. 

hWnd HWND: The window’s handle. 

Related Messages WM_PAINT 

Example This example scrolls down the client area of the window when 


the user clicks the “Do It!” menu item. This invalidates the up- 
per 10 pixel rows. (See Figure 11-28.) Before the WM_PAINT 
message is processed, the program paints a dark rectangle. The 
ExcludeUpdateRgn() function keeps the rectangle from being 
painted in the update region (the region uncovered by scroll- 
ing the window’s client area down 10 pixels). The WM_PAINT 


Figure 11-28. Exclude- 
UpdateRgn() Example. 


logic is set up to paint alternating gray and white bands as the window’s client area is scrolled 


down. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT , ps; 

HDC . hdc ; 

static BOOL bToggle = FALSE ; 

switch, CiMessage) ; /* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
if (bToggle) 
{ 


SelectObject (ps.hdc, 


GetStockObject CLTGRAY_| BRUSH)) ; 


bToggle = FALSE ; 


} 

else 

{ 

SelectObject (ps.hdc, 
GetStockObject (WHITE_BRUSH)) ; 

bTogglé = TRUE ; 

} 

Rectangle (ps.hdc, 0, 0, 500, 500) ; /* paint area */ 

EndPaint (hWnd, &ps) ; 5 

break ; ; ; 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
ScrollWindow (hWnd, 0, 10, NULL, NULL) ; 


hDC = GetDC ChWnd) ; 
ExcludeUpdateRgn choc, hWnd) ; 


SelectObject (hDC, GetStockObject (DKGRAY_BRUSH)) ; 


Rectangle (hDC, 10, 0, 50, 60) ; 
ReleaseDC (hWnd, hDC) ; 


break ; 
[Other program lines] 
ExtTFLOopFILL Win2.0 mWin3.0 eWin3.1 
Purpose Fills an area by replacing a color with the currently selected brush. 
Syntax __ BOOL ExtFloodFill(HDC hDC, int X, int Y, DWORD erColor, WORD wFillType); 
Description This function is similar to FloodFill(). Both functions fill in an area with a color. ExtFloodFillQ) 


has the ability to fill in an area based on renncine one color with the currently selected brush of 


the device context. 
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Uses . Used in painting programs. ——_$__—_— a 
Returns — BOOL. TRUE if the function was successful, FALSE on error. -iiag GENE e et. 


FALSE will be returned if the point is outside the clipping re- § Do It! Quit 
gion, falls on a point that has the border color, or falisona { 7 : 
point that does not have the color specified by crColor ifthe jf 

-. FLOODFILLSURFACE style is used. The painting expands from 
the selected point in all directions until either the boundary 
color is found (FLOODFILLBORDER style), or until no other 
touching areas containing the specified color are located 

’ (FLOODFILLSURFACE style). 


See Also FloodFillQ) Figure 11-29. ExtFloodFill() 


Parameters . Example. 

hDC HDC: The device context handle. 

Xx int: The logical X coordinate to start the painting process. 

Y int: The logical Y coordinate to start the painting process. 

crColor COLORREF: The 32-bit color value specifying either the boundary color or the color of the area to: 
replace. 

wr needa WORD: Specifies which type of filling operation is to be performed. It canbe one of the types 


_ listed in Table 11-12. 


FLOODFILLBORDER Fill an area bounded by one color. The crColor value Siclies the boundary color. This is only 
useful if the area is completely bounded by one color. In this case, ®, ExtFloodFill ) is exactly the 
same as FloodFill(). 


FLOODFILLSURFACE Fill an area by replacing one color. This is useful for areas that do not have a boundary 
rate | =: consisting of only one color. 


Table 11-12. Flood Fill Types. + 


Example This example paints a blue rectangle in the client area, When the user clicks the “Do It!” ay 
item, the square is filled with a solid red brush. (See Figure 11-29.) 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
t ; 


PAINTSBRUCT - ps ; 

HDC hoc ; 

HBRUSH hBrush ; 

switch CiMessage) /* process windows messages */ 
{ 


case WM_ PAINT: 
BeginPaint (hWnd, diay , 
hBrush = CreateSolidBrush (RGB 0, 0, 255)) ; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 10, 10, 50, 50) - /* paint area */ 
EndPaint (hWnd, .&ps) ; 
DeleteObject ChBrush) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_. DOIT: /* User hit the "Do it” menu item */ | 
hDC = GetDc. (hWnd) ; 
hBrush = Createsolsdaruah (RGB (255, 0, 0)) ; 
SelectObject ChDC, hBrush) ; 
ExtFloodFill ChDC, 20, 20, Rep (0, 0, 255), 
FLOODFILLSURFACE) ; 
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ReleaseDC ChWnd, hDC) ; 
DeleteObject ChBrush) ; 


break ; 
[Other program lines] . 
FILLRECT | Win2.0 mWin3.0 mWin3.1 
Purpose Fills a rectangular area with a brush pattern and color. 
Syntax int FillRect(HDC kDC, LPRECT lpRect, HBRUSH hBrush); 
Description This function is similar to Rectangle(), except the borders of 


the rectangle are not drawn and the brush does not have tobe Do It! Q uit 
selected into the device context before use. 


Uses Coloring rectangular areas. 
Returns int, not used. 
See Also Rectangle(), FillRgn() 
Parameters ee 
hDC HDC: The device context handle. Figure 11-30. FillRect() 
lpRect LPRECT: A pointer to a RECT data structure that holds the Example. 
dimensions of the rectangle to paint. 
hBrush HBRUSH: A handle to the brush to use in painting the rectangular area. 
Example The example shown in Figure 11-30 uses FillRect() to draw a square area without a border. 


tong FAR PASCAL WndProc (CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ ‘ 


PAINTSTRUCT ps; “A, 
RECT rRect ; 
-HBRUSH hBrush ; 
switch (iMessage) /* process windows messages */ 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; = 
hBrush = CreateHatchBrush CHS_DIAGCROSS, 
- RGB (0, 0, 255)) ; 
SetRect (&rRect, 10, 10, 50, 50) ; 
FillRect (ps.hdc, &rRect, hBrush) ; 
EndPaint (hWnd, &ps) ; 
DeleteObject (hBrush) ; J 
break ; ; 
[Other program lines] 
- FirtRen ~ gWin2.0- @Win3.0 wWin3.l 
’ Purpose Fills a region with a brush color and pattern. 
_., Syntax BOOL FillRgn(HDC hDC, HRGN hRgn, HBRUSH hBrush); 
Description This is a powerful function for filling areas. Regions of any complexity can be created by combin- 


ing smaller regions using CombineRgn(). Once constructed, these regions can be filled with any 
pattern or brush using FillRgn(). 


Uses Filling areas with a color or pattern. 

Returns BOOL. TRUE if the region was filled, FALSE on error. 

See Also FillRect(), CombineRgn(), praletatern bus; CreateSolidBrush(), CreateHatchBrush() 
Parameters 

hDC HDC: The device éoiitext handle. 

hRgn HRGN: The region handle. 
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hBrush HBRUSH: The handle of the brush to use in filling the region. 
Example The example in Figure 11-31 creates an elliptical region and fills it with a hatched brush. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
£ : 


PAINTSTRUCT ps ; 

HRGN hRgn ; 

RECT ; rRect ; 

HBRUSH hBrush ; 

switch (iMessage) /* process windows messages */ 
ra 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; : 
hBrush = CreateHatchBrush CHS_DIAGCROSS, 
RGB (0, 0, 255)) >; 
SetRect (&rRect, 10, 10, 80, 60) ; 

' hWRgn = CreateEllipticRgniIndirect (&rRect) ; 
FillRgn (ps.hdc, hRgn, hBrush) ; 
EndPaint (hWnd, &ps) ; 

DeleteObject (hBrush) ; 
DeleteObject ChRgn) ; 


break ; 
[Other program lines] 
FLoopF i. Win2.0 mWin3.0 mWin3l 
Purpose ° Fills an area with the currently selected brush. 
Syntax BOOL FloodFill(HDC 2DC, int X, int ¥, DWORD crColor); ~ 
Description FloodFill() demands that the area to be filled be bounded by one color. The area is filled with the 
currently selected brush, starting from X,Y and expanding in all directions until the crColor is 
_ encountered. i 
Uses Used in painting applications for filling irregular shapes with color. . . 
Returns BOOL. TRUE if the area was filled, FALSE on error. An error will occur if X,Y specifies a point 
- outside of the clipping region, or a point that has the same color as crColor. 
See Also ExtFloodFillQ) 
Parameters 
hDC HDC: The device context handle. 
X int: The logical X coordinate to start the painting process. 
Y int: The logical Y coordinate to start the painting process. 


crColor COLORREF: The 32-bit color value of the boundary color. Use the RGB macro to specify a color. 


; E ge neric [-[~ 
[Dott Quit 
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generic |=, 


| Do lt! Quit 
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- sunt Figure 11-32. FloodFill() ames 
Figure 11-31, FillRgn() Example. Figure 11-33. FrameRect() 
Example. a . Example. 
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The program illustrated in Figure 11-32 paints a blue rectangle in the client area. When the user 
clicks the “Do It!” menu item, the square is filled with red. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG (Param) © 


{ 
PAINTSTRUCT ps; 
HDC © hDC ; 
HBRUSH hBrush ; 
HPEN hPen ; 
switch CiMessage) /* process windows messages */ 
t 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hBrush = CreateSolidBrush (RGB (0, 0, 255)) ; 
SelectObject (ps.hdc, hBrush) ; 
hPen = CreatePen (PS_SOLID, 2, RGB (0, 0, 0)) ; 
SelectObject (ps.hdc, hPen) ; 
Rectangle (ps.hdc, 10, 10, 50, 50) ; 
EndPaint ChWnd, &ps) ; 
DeleteObject (hPen) ; 
DeleteObject (hBrush) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) : ; 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
hBrush = CreateSolidBrush (RGB (255, 0, 0)) ; 
SelectObject ChDC, hBrush) ; 
FloodFill ChdC, 20, 20, RGB (0, 0, O0)) ; 
ReleaseDC (hWnd, hDC) ; 
DeleteObject (hBrush) ; 
break ; 
[Other program lines] 4 
FRAMERECT eWin2.0 mWind0 mWin3.l 
Purpose Draws a frame around a rectangle by using a brush. 
Syntax int FrameRect(HDC kDC, LPRECT [pRect, HBRUSH hBrush); 
Description This function draws a frame 1 pixel wide around a rectangle. The brush pattern is used to do the 
painting. 
Uses Not often used. Multiple calls to FrameRect() and InflateRect) can be used to create borders 
with a visible pattern (see the example). 
Returns - int, not used. 
See Also FrameRgn() 
Parameters 
hDC HDC: The device context handle. 
lpRect LPRECT: A pointer to a RECT data structure that contains the dimensions of the ‘actuals to 
frame. 
hBrush . HBRUSH: A handle to a brush to use in painting the border. 
‘Example — This example, illustrated in Figure 11-38, creates an extended frame for a ‘stadia by repeatedly 


painting and then expanding the rectangle. This gets around FrameRect()’ s limitation of only 
painting borders one pixel wide. os < 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 


~ RECT 


rRect ; 
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HBRUSH ; hBrush ; 
- int i; 


switch (iMessage) 


t 


/* process windows messages */ 


case WM_PAINT: 

BeginPaint (hWnd, &ps) ; 

hBrush = CreateHatchBrush CHS_DIAGCROSS, 
RGB (O, Q, 255)) ; 

SetRect (&rRect, 10, 10, 80, 60) ; 

for (i =O; 1<5; itt) 

{ 
FrameRect (ps.hdc, &rRect, hBrush) ; 
InflateRect (&rRect, 1, 1) ; 

} 

EndPaint (hWnd, &ps) ; 

DeleteObject ChBrush) ; 

break ; 


[Other program lines] 


FRAMERGN Win 2.0 Win3.0  mWin3.1 
Purpose Draws a frame around a region using a brush pattern. . 
Syntax BOOL FrameRgn(HDC ADC, HRGN hRgn, HBRUSH hBrush, BoSigi 
int nWidth, int nHeight); : Do It! t a 
Description This function allows you to outline the border ofaregion using & 
a brush pattern. ; 
Uses Used with FillRgn() to paint regions. 
~ Returns BOOL. TRUE if the region was painted, FALSE on error. 
See Also FillRgn(), CreateSolidBrush(), CreatePatternBrush(), 
CreateHatchBrush(), CombineRgn() 
Papencees ceeeiaimeiiaenniemeiianiaa 
hDC HDC: The device context handle. Fig 15 FrameRgnt) 
hRgn HANDLE: The handle of the region to be painted. 
hBrush HBRUSH: The handle of the brush to use in painting the border. Use  CreteSlidBrsh( 
CreatePatternBrush(), etc to create this object. 
. nWidth int: The width of the border in logical units. 
nHeight int: The height. of the border in logical units. 
Example The example shown in Figure 11-34 frames an elliptical region using a hatched brush. The frame 


is set to a width of 8 pixels. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 


PAINTSTRUCT -ps; 
HRGN hRgn ; 
RECT ; rRect ; 
HBRUSH hBrush ; 


switch (iMessage) /* process windows messages */ 
{ : 
case WM_PAINT: 

BeginPaint (hWnd, &ps) ; - ; 

hBrush = CreateHatchBrush CHS_DIAGCROSS, 

RGB (0, 0, 255)) ; 

SetRect (&rRect, 10,°10, 110, 80) ; 

hRgn = CreateELlipticRgnIndirect (&rRect) ; 

FrameRgn (ps.hdc, hRgn, hBrush, 8, 8) ; 

EndPaint (hWnd, &ps) ; 
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DeleteObject (hBrush) ; 
DeleteObject ChRgn) ; 
break ; 


[Other program lines] 


GETBrusHOrG OWin2.0 mWin30 mWin3) 
Purpose _ Finds the brush origin of a device context. 
Syntax DWORD GetBrushOrg(HDC hDC); 
Description In order to smoothly match brush patterns, Windows maintains 
a logical origin as the basis for each brush painting. This origin 
can be moved using SetBrushOrg() and retrieved with 
GetBrushOrg(). The origin only affects brushes that are being 
created. Changing the origin after a brush has been created 
does not affect how the pattern is positioned, unless Un- 
realizeObject() is called first. 
Uses Setting brush patterns so that they do not exactly vera? af- 
eas next to each other. 2 
Returns DWORD. The low-order word contains the X coordinate. The Figure 11-35. GetBrushOrg() 
high-order word contains the Y Ee Sporuillae: Both use device and SetBrushOrg() Example. 
coordinates. 
See Also CreateHatchBrush(), SetBrushOrg(), UnrealizeObject() 
Parameters . 
hDC HDC: The device context handle. 
Example This example paints two rectangles with hatched brushes. The first brush is created with 0,0 as 


the brush origin. The second with 3,3 as the brush origin. This results in the two patterns being 
: offset by three pixels. (See Figure 11-35.) This type of offset can be desirable when it is important 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


va 


PAINTSTRUCT ps ; 

HBRUSH . hBrush ; 

char cBuf [128] ; 

DWORD dwBrushOrg ; 

switch (iMessage) /* process windows messages */ 


case WM_PAINT: 


BeginPaint (hWnd, &ps) ; 

SetBrushOrg (ps.hdc, 0, 0) ; 

hBrush = CreateHatchBrush CHS_CROSS, RGB (0, 0, 255)) ; 
SelectObject (ps.hdc, hBrush) ; 

Rectangle (ps.hdc, 0, 0, 40, 100) ; 

dwBrushOrg = GetBrushOrg (ps. hdc) ; 


_ TextOut (ps.hde, 0, 110, cBuf, wsprintf (cBuf, 


“First Brush Origin = 4d, 2d", 
LOWORD (dwBrushorg), HIWORD (dwBrushOrg))) ; 
SelectObject (ps.hdc, GetStockObject (WHITE_BRUSH)) ; 
DeleteObject ChBrush) ; 
SetBrushOrg (ps.hdc, 3, 3) ; 
hBrush = CreateHatchBrush dis _CROSS, RGB (0, 0, 255)) ; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 41, 0, 80, 100) ; 
dwBrushOrg = GetBrushorg (ps.hde) ; 
TextOut (ps.hdc, 0, 140, cBuf, wsprintf (cBuf, 
“Second Brush Origin = %d, 4d", 
LOWORD (dwBrushOrg), HIWORD taueeianbeanio% 


~ 


473 


to show a separation between two areas, such as to bars on a black and white bar chart. 
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¢ 


EndPaint (hWnd, &ps) 7 
DeleteObject (hBrush) ; 


break ; 

[Other program lines] - 

GeTBVALUE - GETGVALUE - GETRVALUE © Win 2.0 Win3.0 mWin3.1 

Purpose Retrieves a single color value from a 32-bit color value. , 

Syntax . BYTE GetBValue(DWORD rgbColor) 

Description Windows uses 32-bit values for colors. The 32-bit value consists of three bytes of information, 
corresponding to the intensity of the Blue, Green, and Red elements of color. Windows uses this — 
color coding scheme even when the physical device can display only a limited number of colors. 
Missing colors are approximated on most video displays by mixing different colored pixels in the 
same area (dithering). . 

Uses Retrieving an individual color value Fale aie a Wie cgencicen Le Te 
er ean oom ae 
matching colors. 

Returns BYTE, the color value specified. 

See Also RGBO, GetSysColor(), a ‘ a ‘a 
SetSysColors() Figure 11 36. GelBValue(), GetGValue(), GetRValue() 

Parameters Example. 

rgbColor DWORD: The 82-bit color value. 

Example The example (shown in Figure 11-36) displays the blue, green and red color values of the caption 


bar, and also uses the caption color to draw asmall rectangle. In this example the caption color is 
the default focus color of medium blue. 


Long FAR PASCAL WndProc (CHWND hWnd, unsigned iMessage, WORD wParam, LONG iParam) 
{ - ; 


PAINTSTRUCT ps ; 

char cBuf [128] ; 

DWORD dwColor ; 

HBRUSH hBrush ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_PAINT: 

BeginPaint (hWnd, &ps) ; 

dwColor = GetSysColor (COLOR_ACTIVECAPTION) ; 

TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 

“The caption color values are: r = %d, g = &’d, b = 2d", 
GetRValue (dwColor), GetGValue (dwColor), 
GetBValue (dwColor))) ; 

hBrush = CreateSolidBrush (dwColor) ; /* same color */ 

SelectObject (ps.hdc, hBrush) ; / 

Rectangle (ps.hdc, 10, 30, 100, 50) ; 

EndPaint (hWnd, &ps) ; 

DeleteObject (hBrush) ; 


break ; 
[Other program lines] 
GeTCLiPpBox | Win2.0 mWin3.0 mWin31 
Purpose .Gets the dimensions of the smallest rectangle that will enclose the clipping region. 
Syntax int GetClipBox(HDC hDC, LPRECT lpRect), 
Description Clipping regions can have any shape. This function determines the smallest rectangle that will 


fully enclose the clipping area. 
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Uses Used when clipping regions are created. There is no need to call this function to find the update 
region when processing WM_PAINT messages, as the update rectangle is stored in the 
PAINTSTRUCTURE initialized by BeginPaint(). 


Returns int, the type of clipping region. This can be any of the region types in Table 11-13. 
COMPLEXREGION ~The new region has overlapping borders. 
ERROR No new regiort was created. 
NULLREGION The new regicn is empty. 
SIMPLEREGION The new region does not have overlapping borders. 


Table Il -13. Region Types. 


Parameters ; Me | [generic [~ [= 


hDC HDC: The device context handle 


Do lt! Qui 
lpRect LPRECT: A pointer to the RECT data structure that will hold | Dott Quit | 


the dimensions of the bounding rectangle. 


Example This example fills in an irregular clipping region with a gray 
brush. The dimensions of the bounding rectangle of the clip- 
ping region are retrieved with GetClipBox() before the area is  Exemcxomen Remar! 
painted. (See Figure 11-37.) This results in the smallest pos- Figure 11-37. GetClipBox() 
sible painting area to completely fill the clipping region when Example. 


_ painted. 

Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG \Param) 
t | 

PAINTSTRUCT ps ; 

HRGN hRgn ; 

POINT pArray [51 = (10, 10, 50, 40, 90, 20, 60, 0, 

ae 40, 20} ; 
- RECT rRect ; 
switch (iMessage) /* process windows messages */ 
l- 


case WM_PAINT: 
BeginPaint (hWnd, ape) 3 
hRgn = CreatePolygonRgn CpArray, 5, WINDING) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockObject CLTGRAY_BRUSH)) ; 
GetClipBox (ps.hdc, &rRect) ; 
Rectangle (ps:hdc, rRect. left, rRect.top, rRect.right, 

rRect.bottom) ; /* paint gray */ 

EndPaint (hWnd, &ps) ; 
DeleteObject (hRgn) ; 


break ; 
[Other program lines] 
GETCURRENTPOSITION BWin2.0 wWin30 mWin3.l 
Purpose Determines the current logical position in a device context. 
Syntax DWORD GetCurrentPosition(HDC hDC); 
Description Windows keeps track of the location of a logical point set by calls to MoveTo() and LineTo() so 


_ that connected lines can be drawn by specifying only the next point. GetCurrentPosition() deter- 
mines the current location, which will be the starting point for the next line drawn with LineTo 0). 


Uses Useful if the user can reposition a line end in a paint program using the mouse cursor. 
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Returns — -  DWORD, the current position in logical coordinates. The low- 


order word contains the X coordinate. The high-order word : a 
: contains the Y coordinate. Doit! Quit 
See Also MoveTo(), LineTo(), MAKEPOINTQ) Current position =5,35 | 
Parameters . 
hDC HDC: The device context handle. Figure 11-38. GetCurrent- 
Example The example shown in Figure 11-38 draws a line with three ?stéon() Example. 


segments, and then displays the current logical position. This 
is the position of the last call to MoveTo() or LineTo(). 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 

DWORD dwCurPos ; 

POINT pCurPos ; 

char E cBuf [128] ; 

switch (iMessage) /* process windows messages */ 
{ . 


case WM_PAINT: : 
BeginPaint (hWnd, &ps) ; 
MoveTo (ps.hdc, 5, 5) ; 
LineTo (ps.hdc, 200, 5) ; 
LineTo (ps.hdc, 200, 35) ; : : 
LineTo (ps.hdc, 5, 35) ; = 
dwCurPos = GetCurrentPosition (ps.hdc) ; 
pCurPos = MAKEPOINT (dwCurPos) ; 
TextOut (ps.hdc, 70, 10, cBuf, wsprintf (cBuf, 
“Current position = 4d, 4d", pCurPos.x, pCurPos.y)) ; 
eagha ios ChWnd, &ps) ; 


break ; 

[Other program lines] 
GETGVALUE (See the GetBValue description in this chapter.) Win2.0 mm Win3.0. @Win3.L 
GEeTNEARESTCOLOR They Win2.0 mWin3.0 m@Win3.1 
Purpose Determines the most approximate solid color a device can display. 
Syntax | DWORD GetNearestColor(HDC #DC, DWORD crColor); — 
Description The 82-bit color values that. Windows uses to specify display colors can generally Sands more 

colors (256 * 256 * 256 combinations) than a physical device can display. Windows approximates 


colors that cannot be displayed as 
pure colors by dithering, a process 5 
of blending different colored pixels 
to achieve the desired average color 
when viewed at a distance. Get- 
NearestColor() allows the applica- : sai 
tion to determine the nearest pure = Figure 11-39. GetNearestColor(. Jo ona 16- ed VGA 
color that a device can display. In System. 

some cases, it may be desirable to. 

use the nearest pure color instead of the dithered approximation. 


lege es gener. ye pe la 


Uses | The nearest pure color can be used to create solid colored borders, which avoids having 
FloodFill(Q) color filling “leak” through the borders. 
Returns DWORD, the nearest 32-bit color value to crColor that the device can display. 
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See Also 


Parameters 
hDC 


crColor 


Example 
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GetNearestPaletteIndex(), RGBQ 


HDC: The device context handle. 


COLORREF: The 32-bit color value to check. Normally the RGB macro is used to specify this 
value. 


The example illustrated in Figure 11-39 shows how Windows matches a requested RGB color ona 
device with limited capabilities. In this case, a 16-color VGA card was in use. The requested color 
is displayed as a dithered area if used in creating a brush or pen. The nearest pure color the 
display can produce is pure green. 


Long FAR PASCAL WndProc CHWND hWnd, unsignea iMessage, WORD wParam, LONG tParam) 
{ 


PAINTSTRUCT / ps; 

DWORD dwColor ; 

char cBuf (1281 ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_PAINT: 

BeginPaint (hWnd, &ps) ; 

dwColor = GetNearestColor (ps. ides RGB (12, 210, 32)) ; 

TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
“The color closest to RGB 12, 210, 32 = %d, %d, “d", 
GetRValue (dwColor), GetGValue (dwColor), 
GetBValue (dwColor))) ; 

QGP aint ChWnd, &ps) ; 

break ; 


[Other program lines] 


GETOBJECT Win2.0 Win3.0 wgWin3.1 
Purpose Retrieves information about a logical object. 
Syntax int GetObject(HANDLE hObject, int nCount, LPSTR lpObject); 
Description This function retrieves information about logical pens, brushes, fonts, bitmaps, and palettes. The 
information is stored in a data structure pointed to by [pObject. This can either be a LOGPEN, 
LOGBRUSH, LOGFONT, BITMAP, or LOGPALETTE data structure. These structures are defined 
in WINDOWS.H as follows: 
typedef struct tagLOGPEN : ; ° 
f 
WORD LopnStyle; 
POINT LopnWidth; 
DWORD LopnColor; 
} LOGPEN; 


typedef struct tagLOGBRUSH 
{ 


WORD 
DWORD 
int 

} LOGBRUSH; 


lbStyle; 
lbColor; 
lbHatch; 


typedef struct tagLOGFONT | 
{ 


int 
int 
int 
int 
int 
BYTE 
BYTE 


LfHeight; 
LfWidth; 
LfEscapement; 
LfOrientation; 
LfWeight; 
Lfitalic; 
LfUnderline; 
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BYTE 
BYTE 
BYTE ( 
BYTE 
BYTE 
BYTE 
BYTE 

} LOGFONT; 


UfStrikeOut; 


lfCharSet; 


LfOutPrecision; 
LfClipPrecision; 
lfQuality; 
LfPitchAndFamily; 
LfFaceNameCLF_FACESIZEJ; 


typedef struct tagBITMAP 


{ 
int 
int 
int 
int 
BYTE 
BYTE 
LPSTR 

) BITMAP; 


bmType; 

bmWidth; 

bmHeight; 

bmWidthBytes; 

bmPlanes; a 5 
bmBitsPixel; 

bmBits; 


typedef struct tagLOGPALETTE { 


WORD 
WORD 
PALETTEENTRY 

} LOGPALETTE; 


Uses 
Returns 
See Also 


Parameters 
hObject 


nCount 


IpObject — 


Example 


palVersion; 
palNumEntries; 
palPalEntryl1]; 


Commonly used to determine the size of bitmaps and the attributes of stock drawing objects. 
int, the number of bytes retrieved. NULL on error. . 
GetStockObject() 


HANDLE: The pen, brush, font, bit- 
map, or palette handle. 

int: The number of bytestoretrieve. Figure 11-40. GetObject() Example. 

Use the sizeof() operator to specify 

this for each of the data structures involved (see the following example). 

LPSTR: A pointer to the memory area that will contain the desired data. Be sure that this area is 
at least nCount bytes in size. 

In the example shown in Figure 11-40, the color of the stock LTGRAY brush is retrieved and 
displayed i in the window's client area. 


The color of the stock LTGRAY brush = RGB 192, 192, 192 


long FAR PASCAL wndbiee CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 

char cBuf £128] ; 

HBRUSH hBrush ; 

LOGBRUSH lbBrush ; 

switch CiMessage) /* process windows messages */ 


case WM_PAINT: 

BeginPaint (hWnd, Eps) ; 

hBrush = GetStockObject CLTGRAY_BRUSH) ; 

GetObject (hBrush, sizeof (LOGBRUSH), LestR) StGBrushs: 3 

TextOut (ps.hdc, 10, 10, cBuf, sprintf (cBuf, 

“The color of the stock LTGRAY brush = RGB %d, %d, %d", 
GetRValue (lbBrush.lbColor), 
GetGValue (lbBrush.lbColor), 

: GetBValue (lbBrush.lbColor))) ; 

EndPaint (hWnd, &ps) . 

break ; 


[Other program lines] 
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GETPIXEL 
Purpose 
Syntax 
Description 
Uses 


| Returns 
See Also 


Parameters 
hDC 


Example 
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Win2.0 mWind0 mWind) 


Determines the color of a pixel. 


~ DWORD GetPixel(HDC 2DC, int X, int Y); 


This function determines the RGB color value of a point on the device context. 


Used in painting programs to determine existing colors on the client area. Also used to determine 
if a point is within the clipping region. 


DWORD, the 32-bit color value of the pixel. Returns —1 if the point is outside of the current 
cKpping region. 


SetPixel(), SelectClipRgn() 


HDC: The device context handle. 
int: The logical coordinate of the X position to check. 
int: The logical coordinate of the Y position to check. 


This example shows a shaded rectangle being painted, one pixel at a time. The starting pixel 
color is first retrieved using GetPixel(). This color is then incremented and used to set the new 
color of the pixel with SetPixel(). This method of drawing is unacceptably slow. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 


DWORD 


int 


switch (iMessage) 
€ 


dwColor ; 
nRed, nBlue, nGreen, i, j ; 


/* process windows messages */ 
case WM_PAINT: 


BeginPaint (hWnd, &ps) ; 
for (i =0; i1<10; itt) 


{ 
for ¢j = 0; j < 256 ; j++) 
{ 
dwColor = GetPixel (ps.hdc, j, i) ; 
nRed = (GetRValue (dwColor) + j) % 256 ; 
nBlue = (GetBValue (dwColor) + j) %-256 ; 
nGreen = (GetGValue (dwColor) + j) % 256 ; 
SetPixel (ps.hdc, j, i, 
RGB (nRed, nGreen, nBlue)) ; 
} 
} 
e EndPaint (hWnd, &ps).; 
break ; 
[Other program lines] 
GETPOLYFILLMODE Win 2.0 Win3.0 gm Win3.1 
Purpose Determines the current polygon filling mgde for a device context. 
Syntax int GetPolyFillMode(HDC hDC); 
Description The polygon filling mode determines how areas of intersection within the polygon are e painted. 
This is only a factor if the lines defining the polygon intersect. 
Uses Used with SetPolyFillMode() to determine and change the filling mode. 
Returns int, the current polygon filling mode. This can be either mode listed in Table 11-14. - * 
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ALTERNATE The GDI fills in areas between sides 1&2, sides 3&4, etc. 


WINDING The GDI fills in the complete area defined by the outermost lines. This will normally fill the entire interior of 
the polygon, except in cases where more than one intersection of areas defined by the polygon’s lines 
occurs (see the example). ae: . 


Table 11-14. Polygon Filling Modes. Hex 
{| Do i Quit. 


See Also - SetPolyFillMode(), CreatePolygonRgn() 

Parameters | 

hDC -HDC: The device context handles 

Example This example draws the same complex polygon twice, but with 


two different polygon filling modes. (See Figure 11-41.) More 

of the intersected areas are painted with the WINDING mode, a 

but some areas will still be missed. Use clipping regions to as- Figure 1-41. GetPoly- 

sure that all internal areas inside complex areas are painted. FillMode() and SetPolyFill- 
_ Mode() Example. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ , 


£ LTERNATE WINDING 


PAINTSTRUCT ps; . 
POINT pArray CJ] = (10, 10, 50, 40, 90, 20, 5, 110, 
; 60, 0, 80, 90, 0, 70, 110, 60} ; 
int i, nPolyMode ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_PAINT: ca 


BeginPaint ChWnd, &ps) ; 
SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
Polygon (ps.hdc, pArray, 8) ; 
for (4 =0;71<8; itt) 
pArray Cil.x += 80 ; /* offset polygon */ 


nPolyMode = GetPolyFillMode (ps.hdc) ; 
if (nPolyMode == AGTERNOTEDS 


C 
TextOut (ps.hdc, oO 120, “ALTERNATE", 9) ; 
TextOut (ps.hdc, 100, 120, “WINDING", 7) ; 
SetPolyFillMode (ps.hdc, WINDING) ; 
} 
else ; — : 
{ re Fs ° 
TextOut (ps.hdc, 100, 120, "ALTERNATE", 9) ; 
TextOut (ps.hdc, 0, 120, "WINDING", 7) ; 
SetPolyFillMode (ps.hdc, ALTERNATE) ; 
+. 
S Potygon (ps.hdc, pArray, 8) ; 
\ EndPaint (hWnd, &ps) ;° 
break ; 
{Other program lines] oe 
GETRGNBox gWin2.0 oOWin30 mWin3.1 
Purpose Determines the bounding rectangle of a region. 
Syntax int GetRgnBox(HRGN hRgn, LPRECT lpRect); 
Description | ~ Regions can have any arbitrary shape. This function calculates the minimum size rectangle that 


will fully enclose a region. 
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Uses Handy for computing the minimum size rectangle to paint in order to entirely fill a region. Also 
handy for computing the rectangle size to invalidate in order to force painting of part of the 
window’s client area. 


Returns int, the region's type. This can be any of the types listed in Table 11-15. _ 


COMPLEXREGION The region has overlapping borders. 

ERROR No new region was created. 

NULLREGION The region is empty. 

SIMPLEREGION — The region does not have overlapping borders. 
Table 11-15. Region Types. 


Returns NULL if hAgn is not a handle of a valid region. 


See Aiso GetClipBox(), InvalidateRgn() 
Parameters 
hRgn HRGN: The region’s handle. 
lpRect LPRECT: A pointer to a RECT data structure that will hold the 
dimensions of the bounding rectangle. sssifrinnat _—. 
Example The polygonal area shown in Figure 11-42 is painted by setting Figure 1 L 2 GetRgnBo( ) 


the region as a clipping area and painting the minimum sized Example. 
rectangle that encloses the region with a gray brush. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


PAINTSTRUCT ps ; 

HRGN hRgn ; 

POINT pArray [5] = (10, 10, 50, 40,°90, 20, 60, 0, 
40, 20} ; 

RECT ; rRect ; 

switch (iMessage) /* process windows messages */ 

{ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hRgn = CreatePolygonRgn. CpArray, 5, WINDING) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockObject CLTGRAY_| BRUSH)) ; 
GetRgnBox ChRgn, &rRect) ; 
Rectangle (ps.hdc, ERECEs oe rRect.top, rRect.right, 

rRect.bottom) ; /* paint area */ 

EndPaint (hWnd, &ps) ; 3 
DeleteObject ChRgn) ; 


break ; 
[Other program lines] 
GeTROP2 | aWin2.0 Win3.0 om Win3.1 
Purpose Determines the current raster drawing mode for a device context. 
Syntax int GetROP2(HDC hDC); 
Description The default R2_COPYPEN paints the pen color regardless of the underlying colors. With the other 


drawing modes, the pen is drawn on the device context after comparing the pen color to the 
existing color at each X,Y position being drawn. With color devices, each of the three primary 
colors is dealt with separately, using the same binary logic. The blue element of the pen color is - 
compared to the blue element of the pixel, etc. 
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Uses - Only a few of the ROP2 operations are typically used. The common ones are R2_NOT, which 
- makes the pen always visible, and R2_XORPEN, which makes the pen line disappear if the same 
line is drawn twice. 


Returns int, the current drawing mode. This value is one of the i6 values shown in Table 11-16. In the 

5 Boolean Operation column, the “P” stands for the pen color value, and the “D” stands for the 
display color value. For simplicity, the explanations are in terms of a black and white display. For 
color displays, the same logic is applied to each cole element Bet, isi green). 


; - Boolean Operation’ mients 
R2_BLACK 0 ae . Aiea black. 


R2_WHITE 1! - Always white 

R2_NOP D No affect on display. 

R2_NOT - ~D Invert display under line. 

R2_COPYPEN P , Pen color painted regardless of display. 
R2_NOTCOPYPEN ~P Pen color inverted regardless of display. . 
R2_MERGEPENNOT P|~D ; 
R2_MASKPENNOT P&~D f 

R2_MERGENOTPEN ~PID | ! 

R2_MASKNOTPEN ~P&D 

R2_MERGEPEN PID 

R2_NOTMERGEPEN —~(PID) 

R2_MASKPEN — P&D 

R2_NOTMASKPEN ~(P & D) 

R2_XORPEN PAD A black pen inverts the device pixels. Drawing 


twice at the same location erases the line. 
R2_NOTXORPEN ~ (PAD) 


' Table 11-16. Raster Operation Codes. 


[E[generic [> [= 


See Also The SetROP2() example shows all 16 modes contrasted on a black 
| and white background. ee | Do ttt Quit 
’ Parameters 
hDC HDC: The device context handle. 
Example This example, as shown in Figure 11-48, paints the client area = § 


with a blue hatched brush. When the user clicks the “Do It!” menu 
item, the ROP drawing mode is checked. If the device context for 
the client area is not already set to the R2_XORPEN mode, that 
mode is selected and a line drawn diagonally. Repeatedly click- 
ing the “Do It!” menu item draws and then erases the line, leaving 


the background intact. Figure 11-43. GetROP2Q) 
; . ' Example. 
3 FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD ae LONG lParam) 
PAINSSTRUCT ps 4 
HPEN : hPen-; 
- HBRUSH hBrush ; we 
HDC hDC ; nie 
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rClient ; 


switch (CiMessage) /* process windows messages */ 


case WM_PAINT: 


BeginPaint ChWnd, &ps) ; 

SelectObject (ps.hdc, GetStockObject CBLACK_| PEN)) ; 

hBrush = CreateHatchBrush CHS CROSS, RGB (0, 0, 2559) ; 

SelectObject (ps.hdc, hBrush) ; /* select btue brush iy 

GetClientRect (hWnd, @rclient) : 

Rectangle (ps.hdc, rClient.left, rClient.top, 
rClient.right, rClient.bottom) ; 

EndPaint (hWnd, &ps) ; 

DeleteObject (hBrush) ; 

break ; 


case WM_COMMAND: /* process menu items */ 


‘Other program lines] 


switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC (hWnd) ; 
hPen = CreatePen (PS_SOLID, 4, RGB (255, 0, 0)) ; 
SelectObject (hDC, hPen) ; 
if (GetROP2 (hDC) != R2_XORPEN) 
SetROP2 (hDC, R2_XORPEN) ; 
MoveTo (hdc, 0, 0) ; 
LineTo (hDC, 100, 100) ; 
ReleaseDC (hWnd, hDC) ; 
DeleteObject (ChPen) ; 
break ; 


GETRVALUE (See the GetBValue section in this chapter.) | mWin2.0 mWin3.0 


GetSTocKkOBsEcT 


@Win2.0 mWin30 


@ Win 3.1 


@ Win 3.1 


Purpose Retrieves a handle to one of the predefined objects that are always available to Windows applica- - 


tions. 


Syntax HANDLE GetStockObject(int nindex); 

Description ~ Windows maintains a small set of stock drawing objects, which can be used without creating the 
object by just retrieving a handle to the stock object with Gobinonen: The default objects 
are the BLACK_PEN, WHITE_BRUSH, and SYSTEM_FONT. 


Uses Using stock objects saves time and memory. 

Returns HANDLE, the object handle. NULL on error. 

See Also GetSysColor(), GetSystemMetrics(), SelectObject() 

Parameters . - : 
nIndex int: An index to one of the stock objects, which can be any of the values listed in Table 11-17. 


BLACK_BRUSH 
DKGRAY_BRUSH - 
GRAY_BRUSH 
HOLLOW_BRUSH 


LTGRAY_BRUSH 
NULL_BRUSH 


Asolid black brush, 
A dark gray brush. - 
A gray brush. 


No painting is done inside of an object, ‘such asa rectangle, if this style is chosen. Handy for 


creating borders. 


. Alight gray brush. 


Same as HOLLOW_BRUSH. 
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Table 11-17. continued 


WHITE_BRUSH _ Awhite brush. This paints solid wie: ieiead of not ‘pata the interior with a 


HOLLOW_BRUSH. This is the default brush. 
BLACK_PEN | A single pixel wide black pen. This is the default pen. 
NULL_PEN No pen drawing is done. This is a wey to eliminate borders drawn with objects such as 
rectangles. 
WHITE_PEN A white pen one pixel wide. 
ANS!_FIXED_FONT ANSI fixed pitch font. 
ANSLVAR_FONT —_ ANS variable pitch font. 


DEVICE_DEFAULT_FONT The default font for a device. This is important for some printers that have a built-in font that is 
. faster than graphics fonts. 


OEM_FIXED_FONT A device supplied font. 
SYSTEM_FONT The system font. This is the default font used ny Windows for captions ¢ and menus. 
SYSTEM_FIXED_FONT The old Windows 2.0 fixed font. 
DEFAULT_PALETTE The default color palette. 
Table 11-17. Stock Objects. 
Cautions. Do not attempt to delete stock objects. Be sure the CS_HRE- REE : generic Se bake 
DRAW and CS_VREDRAW class styles are specified in the . Do it! Quit 
window's class definition before using stock brushes. Stock ea 
brush origins cannot be changed (see SetBrushOrg() forde- [em “ANS var Fo NT 
tails on brush origins). mb ee 


Example This example, shown in Figure 11-44, uses three stock objects 
to paint the client area: a stock pen, a stock brush, anda stock [=i EaEs 
font. All of them are selected into-the client area device con- Figure 11-44. GetStock- 
text. The text color is changed to equal the window caption Object() Example. 
color. The transparent drawing mode is also selected. 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ; 


PAINTSTRUCT . ps ; 
RECT rClient ; 

= switch (iMessage) /* process windows messages */ 
{ : 


case WM_PAINT: 
BeginPaint (hWnd, tps: : 
SelectObject (ps.hdc, GetStockObject (BLACK_PEN)) ; 
SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
SelectObject (ps.hdc, GetStockObject CANSI_VAR_FONT)) ; 
SetTextColor (ps.hdc, GetSysColor (COLOR_CAPTIONTEXT)) ; 
SetBkMode (ps.hdc, TRANSPARENT) ; 
GetClientRect: (hWnd, &rClient) ; 
Rectangle (ps.hdc, rClient.left, rClient.top, 

rClient.right, rClient.bottom) ; 

TextOut (ps.hdc, 10, 10, "ANSI VAR FONT", 13) ; 
EndPaint (hWnd, &ps) ; 
break ; 


[Other program lines] 
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GETSysCoLor 


BWin20 mWin30 mWin3.1 
Purpose Retrieves one of the system colors. 
Syntax DWORD GetSysColor(int nJndex); 
Description The system colors are the colors of the objects Windows paints, such as window caption bars, 
scroll bars and the desktop surface. These colors can be modified by the user using the Windows 
Control Panel application. The system colors are shared by all applications running on the 
system. — 
Uses The system colors are frequently good choices for use (—[- ge neri¢. ©. | scl Fase 
in painting a window’s client area. Their choice as- Do tt! Quit 
sures that the colors are consistent with the way the | 
user has set up his or her color choices. ‘Mimics.Ca ption: Colors 
Returns DWORD, the 32-bit color value extracted. - zs : é : cee eee 
See Also SetSysColors() Figure 11-45. GetSysColor() Example. 
Parameters 
nindex int: One of the values in Table 11-18. 


COLOR_ACTIVEBORDER 


COLOR_ACTIVECAPTION 
COLOR_APPWORKSPACE 
COLOR_BACKGROUND 
COLOR_BTNFACE . 
COLOR_BTNSHADOW 
COLOR_BINTEXT 
COLOR_CAPTIONTEXT 
‘COLOR_GRAYTEXT 


COLOR_HIGHLIGHT 
COLOR_HIGHLIGHTEXT 
COLOR_INACTIVEBORDER 
COLOR_INACTIVECAPTION 
COLOR_MENU 
COLOR_MENUTEXT 
COLOR_SCROLLBAR 
COLOR_WINDOW 
COLOR_WINDOWFRAME 
COLOR_WINDOWTEXT 


Table 11-18. System Colors. . 
This program, illustrated in Figure 11-45, writes text in a colored rectangle. The rectangle brush 


Example 


The active window poe? 
The active window caption. 
The background color for MDI (multiple document interface) applications. 
The desktop (background on which all programs and icons are painted). 
Button face-color. . 

Button edge color. 

Button text color. 

The caption text color. | 


Grayed (disabled) menu item text color. The retumed color is set to zero if the display does not 
support a solid gray color. 


Selected item color in a control. 


~ Text color in a selected control. 


Color of an inactive window border. 

Color of an inactive window caption. 

The menu background color. 

The menu text color. os 
The scroll-bar gray area. 

The window background color. 

The window frame color. 

The color of text in a window. 


color and the text color are both set to match that of the caption, assuring that the color combi- 


_~ 
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nation will have visible letters. Note how GetTextExtent() is used to size the rectangle to match 
the length of the text string. 


bong FAR PASCAL WndProc CHWND hWnd, unsigned ies sogee WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT , ps; : 

‘char cBuf CJ = (“Mimics Cepeion Colors"? ; 
_ DOWORD . dwColor ; 
' HBRUSH hBrush ; 


“switch CiMessage) 
{ 


/* process windows messages */ 


_case WM_PAINT: 

BeginPaint ChWnd, &ps) ; 
dwColor = GetSysColor (COLOR_ACTIVECAPTION) : 
-hBrush = CreateSolidBrush (dwColor) ; /* same color */ 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 10, 10, ; 

20 + Cint) GetTextExtent (ps.hdc, cBuf, 

strlen CcBuf)), 30) ; 

SetTextColor (ps.hdc, GetSysColor (COLOR_CAPTIONTEXT)) ; 
SetBkMode (ps.hdc, TRANSPARENT) ; 
TextOut (ps.hdc, 15, 12, cBuf, strlen (cBuf)) ; 
EndPaint (hWnd, &ps) ; 
DeleteObject (hBrush) ; 


: break ; 
[Other program lines] 
GetUppaTEREcT gWin20 mWin3.0 mw Wind. 
Parpose Retrieves the dimensions of the invalid rectangle in the window’s client area. . 
Syntax. BOOL GetUpdateRect(HWND hWnd, LPRECT lpRect, BOOL bErase); 
- Description The invalid rectangle is the area that will be has the next time a WM_PAINT message is 
processed. 
Uses This function is used outside of the WM_PAINT message processing logic of the program. Within 
, the WM_PAINT logic, the PAINTSTRUCT data structure filled by BeginPaint() provides the oe 
” mensions of the update rectangle. (BeginPaint()validatesthe ,_ " 
update region, so GetUpdateRect() will always return an Se gene NG iio. 2 
empty rectangle if used after BeginPaint()). The usual reason 
for retrieving the update region is to validate it, so that Win- Ffesd in Update Region 
dows does not paint the region. This technique can be useful if 
Be a number of separated graphics operations are to be per- 
formed. The entire painting operation can-be-done at the end 
by invalidating the client area with InvalidateRect(). 
Returns BOOL. TRUE if the update rectangle is not empty, FALSE if it Figure 11-46. GetUpdate- 
is empty, meaning that none of the client area is invalid. Rect() Example. 
See Also ValidateRect(), GetUpdateRgn(), ValidateRgn(), BeginPaint() 
Parameters 
hWnd HWND: The window’s handle. 
lpRect — LPRECT: A pointer to a RECT data structure that will hold the invalid rectangle dimensions. If 
the window was created with the CS_OWNDC style, the units are logical coordinates. Otherwise, 
. the units are device coordinates. - 
BOOL: Set to TRUE to erase the barkground of the invalid rectangle, FALSE to wat erase the 


background. Erase the beckarrend by sending a WM_ERASEBKGND message. 
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Related Messages WM_PAINT, WM_ERASEBKGND . ‘ 


Example This example, illustrated in Figure 11-46, scrolls the window down and paints text in the update 
region at the top of the client area when the user clicks the “Do It!” menu item. Scrolling adds the 
exposed region to the update region, which would normally mean that the text would be painted 
over immediately by the next processing of a WM_PAINT message. However, the update rect- 
angle is retrieved and validated. This keeps Windows from sending a WM_PAINT message, so the 
text remains visible. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HOC hoe ; 
RECT rUpdate ; 
switch CiMessage) /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
ScrollWindow (hWnd, 0, 20, NULL, NULL) ; 
hDC = GetDC (hWnd) ; 
TextOut (hdc, 0, 0, “Text In Update Region", 21) ; 
GetUpdateRect ChWnd, &rUpdate, FALSE) ; 
ValidateRect (hWnd, &rUpdate) ; 
ReleaseDC ChWnd, hDC) ; 


break ; 
[Other program lines] 
SEIU EDATERGN OWin2.0 @Win30 gWin3.1 
Purpose Copies the update region of a window's client area to hRgn. 
Syntax _ int GetUpdateRgn(HWND hWnd, HRGN hRgn, BOOL bErase); 
Description This function is similar to GetUpdateRect(), except the invalid area of the window’s client: area is 


passed as a region instead ofa rectangle. Invalid parts of the client area are caused by scrolling, 
resizing, or uncovering parts of the window that were under other windows or dialog boxes. 
Uses The update region can be passed to ValidateRgn() to avoid having the region repainted. This only 
works outside of the WM_PAINT logic section of the program, as BeginPaint() automatically 
validates the client area in preparation for repainting. 


Returns int, the type of region returned. This can be any of the region types listed in Table 11-19. 


COMPLEXREGION The region has overlapping borders. 


ERROR No region was created. 
NULLREGION ‘The region is empty. 
SIMPLEREGION The region does not have overlapping borders. 
Table 11-19. Region Types. 
See Also ValidateRgn(), GetUpdateRect(), ValidateRect() 
Parameters . 
hWnd HWND: The window handle. 
hRgn HRGN: The handle of the region that will hold the update region. The region must exist prior to 
calling GetUpdateRgn(). Use CreateRectRgn() to create a region prior to calling this function 
(see the example). 
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,_ OFrase BOOL: TRUE if the background should be erased, FALSE if 


not. ese ee 
Related Messages WM_PAINT 7 Do lt Quit 
P prext In Update Region 
Example This example, which is shown in Figure 11-47, scrolls the client 


area down, and then writes in the client area when the user 
clicks the “Do It!” menu item. Normally, the text would be 
erased immediately by repainting the invalidated region, % 
which was uncovered by scrolling. In this case, the invalid re- Figure 11-47, GetUpdate- 
gion is validated before a WM_PAINT message is ener RgnQ) and ValidateRgn( ) 
which keeps the text from being erased. Example. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
4 . 


HDC hDC ; 

HRGN hRgn ; 

switch (iMessage) /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 


case IDM_DOIT: /* User hit the “Do it” menu item e/ 
ScrollWindow ‘Chiind, 0, 20, NULL, NULL) ; 
hDC = GetDC (hWnd) ; 
TextOut (hdc, 0, 0,” "Text In Undate Region", 21) ; 
hRgn = CreateRectRgn (0, 0, 1,- i ; /*. initialize om, 
GetUpdateRgn (hWnd, hRgn, FALSE) ; — , 
ValidateRgn (hWnd, hRgn) ; 
ReleaseDC (hWnd, hDC) ; 


break ; 
[Other program lines] 
INFLATERECT | gWin2.0 mWin30 mWin3.l 
Purpose Increases or decreases the size of a rectangle. 
Syntax void InflateRect(LPRECT (pRect, int X, int Y); 
Description ~ Rectangles are used not only as drawing objects, but also to 


define the borders of ellipses, chords, arcs, etc. InflateRect() 
allows expansion or contraction of a rectangle in a single func- 
tion call. : 


Uses A fairly common need in graphics programs is to create a bor- 
der containing multiple lines. InflateRect() allows consistent 
changes to the dimensions of a rectangle without needing to 

-. deal with each of the rectangle’s four elements. 


Returns No returned value (void). 

See Also SetRect(), Rectangle() - 

Parameters laps dttleraeetuanearicatcransd rr tese erences 

lpRect LPRECT: A pointer to a RECT data structure that holds the Figure 11-48. InflateRect() 
rectangle that is to have its size changed. Example. 
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int: The amount to er the horizontal size. Positive values increase negative values decrease. 
The size is changed by this amount on both the left and right sides. 


int: The amount to change the vertical size. Positive values increase, negative values decrease. 


- The size is changed by this amount on both the top and bottom dimensions. 


As shown in Figure 11-48, five concentric rectangles are drawn by repeatedly calling Inflate- 
Rect() to enlarge the rectangle. Note that the stock object NULL_BRUSH is used for the rect- 
angle filling brush to avoid painting over the internal rectangles. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 
PAINTSTRUCT ps ; 
RECT rRect ; 
int 5 Oar 
switch (iMessage) /* process windows messages */ 
C , 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SelectObject (ps.hdc, Cote tockopters. CNULL_| BRUSH)? 7 
SelectObject (ps.hdc, GetStockObject (BLACK_PEN)) ; 
SetRect (&rRect, 30, 30, 90, 90) ; 
for (=O; 1<5; itt) 


{ ‘ 
Rectangle (ps.hdc, rRect.left, rRect.top, 
rRect.right, rRect.bottom) ; 
InflateRect (&rRect, 4, 4) ; 
} 
EndPaint (hWnd, &ps) ; 
break ; 
[Other program lines] 
INTERSECTCLIPRECT | mWin2.0 mWin3.0 mWin3t 
Purpose Creates a new clipping region by combining the existing rectangle and a rectangular region. Only 
the overlapping region common to the two areas remains within the clipping region. 
Syntax . int IntersectClipRect(HDC hDC, int X/, int YJ, int X2, int Y2); 
Description . This is identical to using CombineRgn() with the RGN_AND clipping style, with one of the re- 
gions being rectangular. Limiting a clipping region to a rectangular portion of the client area is 
such a common need, that this specialized function is provided. . 
Uses Restricting painting to a rectangular area on the screen, in addition to the restrictions of the 
existing Clipping region. 
Returns int, the result of the function. This can be any of the region types in Table 11-20. 


COMPLEXREGION 
ERROR 
NULLREGION 

SIMPLEREGION 


Table 11-20. Region Types. 


See Also 


The new region has overlapping borders. 

No new region was created. . 

The new region is empty. 

The new region does not have overlapping borders. 


CombineRgn(), CreateRectRgn() 
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Parameters pee ek My bo ¥ : 
hDC HDC: The device context handle. A f= generic: + {- = 
Xl int: The logicaLX coordinate of the upper left corner of the bound- 1 Dolt! @ uit 
| ing rectangle. é 
Yl. _ int: The logical Y coordinate of the upper left corner of the bound- i 
4 ing rectangle. 
X2 int: The logical X coordinate of the lower right corner of the § 
bounding rectangle. Figure 11-49. Intersect- 
y2 int: The logical Y coordinate of the lower right corner of the ClépRect() Example. 
bounding rectangle. 
Example The example, which is shown in Figure 11-49, creates a clipping region from the intersection of 


an elliptical region and a slightly smaller rectangle. A larger area is painted with a gray pra; but 
only the area within the clipping region is painted. 


long FAR PASCAL WndProc CHWND hWnd, Gnsigned inosine; WORD wParam, LONG lParam) 
€ 


PAINTSTRUCT . ps ; 

HRGN hRgn ; 

switch CiMessage) /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hRgn = CreateEllipticRgn (10, 10, 100, 40) ; 
- SelectClipRgn Cps.hde, hRgn) ; 
- IntersectClipRect (ps.hdc, 20, 10, 90, 40) ; 
- SelectObject (ps.hdc, GetStockobject CLTGRAY. BRUSH)) ; 
_- Rectangle (ps.hdc, 5, 5, 500, 500) ; 
EndPaint (hWnd, &ps) ; 
DeleteObject ChRgn) ; 


break ; 
[Other program lines] 
INTERSECTRECT _ mi Win2.0 mm Win3.0) wWin3.1 
Purpose Computes the rectangle of intersection of two other rectangles. Pa 
Syntax int IntersectRect(LPRECT IpDestRect, LPRECT lpSrc1Rect, (— [generic [> [a :. 
LPRECT lpSrc2Rect), 7 r ok . 
= ss | Do lt! Quit 
Description When two rectangles overlap, the area of overlap is always rectan- 
a gular. IntersectRect() computes the rectangle of the overlap area. _ . 
Uses Useful for clipping rectangles, and for shading. 
Returns _ int. TRUE if there is an area of intersection, FALSE if the two 
rectangles do not overlap. 
See Also CombineRgn() 
Parameters 
lpDestRect LPRECT: A pointer to the RECT data structure that will hold the 
dimensions of the rectangle of overlap. If there is no overlap, the Figure 11-50. 


ee will be empty (all zeros). IntersectRect() Example. - 
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LPRECT: A pointer to a RECT data structure holding the dimensions of a source rectangle. 


LPRECT: A pointer to a RECT data structure holding the dimensions of the second source rect- 
angle. ; 

This example creates a third rectangle from the intersection of two others. The third rectangle is 
painted with a hatched brush, as shown in Figure 11-50. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
€ Be ; 


PAINTSTRUCT pS; 
- RECT r1, r2, r3 
HBRUSH hBrush ; 
switch (iMessage) ; ./* process windows messages */ 
{ 


case WM_PAINT: 

BeginPaint ChWnd, &ps) ; 

SetRect (&r1, 10, 10, 70, 80) ;. 

SetRect (&r2, 50, 50, 100, 100) ; 

IntersectRect (&r3, &ri, &r2) ; 

SelectObject (ps.hdc, GetStockObject (GRAY_BRUSH)) ; 

SelectObject (ps.hdc, GetStockObject (BLACK_PEN)) ; 

Rectangle (ps.hdc, ri.left, r1.top, ri. right, 

r1.bottom) ; 

Rectangle (ps.hdc, r2. left, r2.top, r2.right, 
r2.bottom) ; 

hBrush = CreateHatchBrush CHS —DIAGCROSS, 
RGB (0, 0, 255)) ; 

SelectObject (ps.hdc, nerdsh) ; 

Rectangle (ps.hdc, r3.left, r3.top, r3.right. 
r3.bottom); — 

EndPaint (hWnd, &ps) ; 

DeleteObject ChBrush) ; 

break ; 


[Other program lines] 


INVALIDATERECT mWin20 mWin30 wWin3l 


Returns 
See Also 


Parameters 
hWnd 


Adds a rectangular area to a window’s update region, so that it is repainted on the next 
WM_PAINT cycle. 


void InvalidateRect(HWND hWnd, LPRECT lpRect, BOOL bErase) ; 


Invalidating a rectangular region forces Windows to send a WM_PAINT message to the applica- 
tion. The invalidated area is the only part painted. 


Frequently used to force a repainting of the entire client area. Also useful in programs which 
have “smart” WM_PAINT processing logic, which only repaints areas that are invalid. Invalidat- 
ing all or part of the client area is a quick way to activate the painting logic from another part of 
the program. 

No returned value (void). 


InvalidateRgn(). UpdateWindow() can be used to force an immediate WM_PAINT message, 
rather than waiting for the message to be processed via the system message queue. 


HWND: The window handle. 
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lpRect __ LPRECT: A pointer to a RECT data structure containing the 


dimensions of the rectangle to invalidate. Set to NULL to in- me g eneric’ Iv [a 
| . validate the entire client area. | Do tt Quit i 
bErase BOOL: TRUE if the background should be erased during re- : 


painting, FALSE if not. This becomes the fErase element of the 
PAINTSTRUCT data structure filled by cece: 


- Related Messages WM_PAINT 


Example This example shows graphically, see Figure 11-51,thatonlythe 
update region gets painted when a WM_PAINT message is pro- Figure 11-51. Invalidate- 
‘cessed. When the user clicks the “Do It!” menu item, arectan- _Rect() Example. 
gular region at the top left of the client area is invalidated, 
forcing a WM_PAINT message. The logic for handling WM_PAINT messages alternately paints a 
large area gray or white. Only the update rectangle ends up painted. 


. tong FAR-PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 

HDC hoc ;° 

static BOOL bToggle = FALSE ; ¢ 
RECT rUpdate ; ; , 

HRGN hRgn ; 

switch (iMessage) /* process windows messages */ 
{ j 


case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
if (bToggte) 
{ 


SelectObject (ps.hdc, 
GetStockobject (LTGRAY_ BRUSH)) ; 
es = FALSE ; 


} 
else 
{ i 
SelectObject (ps.hdc, 
GetStockObject (WHITE_BRUSH)) ; 
bToggle = TRUE ; 3 
} 


Rectangle (ps.hdc, 0, 0, 500, 500) ; 
EndPaint (hWnd, &ps) ; 
break ; 

case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hRgn = CreateRectRgn (0, 30, 50, 60) ; 
InvalidateRgn (hWnd, hRgn, TRUE) ; 
DeleteObject (ChRgn) ; 


break ; : 

[Other program lines] ' 
INVALIDATERGN mWin2.0 mWin30 mWin31- 
Purpose Adds a region to a window's update region, so that it is repainted on the next WM_PAINT cycle. 
Syntax void InvalidateRgn(HWND hWnd, HRGN hRgn, BOOL bErase); ; 
Description Invalidating a rectangular region forces Windows to send a WM_PAINT message to the epee 

tion. The invalidated area is the only part painted. 
Uses Similar to InvalidateRect(), except that a region is used to pass the dimensions of the invalid 


area rather than a rectangle. Regions can be of any arbitrary shape and complexity. When the 
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Returns 
See Also 


Parameters 
hWnd 


hRgn 
bErase 


Related Messages 
Example 
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WM_PAINT message is processed, the invalid area will be the smallest rectangle that encom- 
passes the region. 


No returned value (void). 
ValidateRgnQ), InvalidateRect() 


HWND: The window handle. 

HRGN: The handle of the region to pass as the invalid part of the client area. 
BOOL: TRUE if the background should be erased during repainting, FALSE if not. This becomes 
the Erase element of the PAINTSTRUCT data structure filled by BeginPaint(). 

WM_PAINT 

When the user clicks the “Do It!” menu item, a small rectangular region is invalidated on the | 
client area. Windows, therefore, sends a WM_PAINT message to the application’s message queue. 


The WM_PAINT logic is set to paint a large area alternately gray or white, switching each time 
the message is received. Only the invalidated area is ultimately painted. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . : : 


PAINTSTRUCT ps ; 
HDC hDC ; 
static BOOL bToggle = FALSE ; 


Rectangle (ps.hdc, r3.left, r3.top, r3.right, 
; r3.bottom) ; 
EndPaint ChWnd, &ps) ; 
DeleteObject (hBrush) ; 


break ; 
[Other program lines] 
INVERTRECT wWin2.0 mWin30 mWin3.l 
Purpose Inverts the color of every pixel within a rectangular area. 
Syntax void InvertRect(HDC hDC, LPRECT lpRect); 
Description The colors are inverted by applying a logical NOT operation to each RGB element of each pixel 
within the rectangle. For example, white becomes black and black becomes white. This inversion 
makes the rectangle visible over the background, including colored backgrounds. Inverting a 
second time restores the area. pats oF 
Uses Inverting an area is a way to show a mouse selection. Ig eneric iM Es | 
Returns No returned value (void). 
See Also InvertRgn() 5 
Parameters . ae onet 
hDC HDC: The device context handle bX 
lpRect LPRECT: A pointer to a RECT data structure containing the ose i! 
dimensions of the rectangle to invert, in logical coordinates. OO O5 C5 C50 a 
Example When the user clicks the “Do It!” menu item, a rectangular ree —& ate 


gion is inverted, as shown in Figure 11-52. Clicking a second Figure 11-52. InvertRect() 
time restores the client area to its previous state. Example. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{t a 


PAINTSTRUCT ps; 

HDC hDC ; 

RECT rClient, rinv ; 

HBRUSH hBrush ; 

switch CiMessage) /* process windows messages */ 
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-{ 
case WM_PAINT: 

BeginPaint ChWnd, &ps) ; 

hBrush = CreateHatchBrush (HS_DIAGCROSS, RGB (0, 0, 0)) ; 

SelectObject (ps.hdc, hBrush) ; 

GetClientRect ChWnd, &rClient) ; 

Rectangle (ps.hdc, rClient. lett: rClient. top, 
rClient. right, rClient.bottom) ; 

EndPaint (hWnd, &ps) ; 

Deletedbject (hBrush) ; 

break ; 

case WM_ COMMAND: /* process menu items */ 

switch (wParam) 

{ . 

case IDM_DOIT: re fal User. hit the “Do it” menu item */ 
hDC = GetDC ChWnd) ; 
SetRect (&rinv, 20, 20, 70,°50) ; 
InvertRect (hOC, &riInv) ; 
ReleaseDC ChWnd, hDC) ; 

break ; 

[Other program lines] 

InVERTRGN _ . mWin2.0 mWin3.0 mWin3.1 

a Bat SE A EZ a a I ESN aS a a TE a EE SI 

Purpose Inverts the color of every pixel within a region. 

Syntax BOOL InvertRgn(HDC hDC, HRGN hRgn); 

Description — The colors are inverted by applying a logical NOT operation to each RGB element of each pixel 
within the region. For example, white becomes black and black becomes white. This inversion 
makes the region visible over the background, including colored backgrounds. Invertinga second 
time restores the area. 

Uses are a region visible on the screen in a way that i is easy to [= [qeneric: [= EE 

Returns BOOL. TRUE if the region was inverted, FALSE on error. Bo it auj 

Me, i . n> c™ 

See Also InvertRect() Seco: ° 

: $o2s os 

Parameters | Sates: Soo 

hDC HDC: The device context handle. a ty, poese oo 

hRgn 2. S ‘HRGN : The handle of the region to be inverted. Figure 11-59. InvertRgn() 

Example The example shown in Figure 11-53 inverts an elliptical region £xample. 


-. when the user clicks the “Do It!” menu item. Clicking the menu 
item a second time restores the client area. 


lone FAR PASCAL wndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
C.: 


PAINTSTRUCT . ps; 

HDC hDC ; 

RECT - ; ; rClient ; 

HRGN hRgn ; 

HBRUSH hBrush ; 
; ‘switch CiMessage) ' /* process windows me 
. { s ‘ = 
de 


bls case WM_PAINT: | : 
me! BeginPaint (hWnd, &ps) ; 


SelectObject (ps.hdc, hBrush) ; 
GetClientRect ChWnd, @rclient) ; 
Rectangle (ps.hdc, rClient. left, EGP Lent: top, 
rClient. right, rClient.bottom) ; 

EndPaint ChWnd, &ps) ; 

dDeletedbject ChBrush) | 3 

break ; o ce ts See 
case WM_ COMMAND: ; /* process menu items 
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ssages */ ~ 


a hBrush = CreateHatchBrush CHS —PIAGCROSS, RGB (0, 0, 0)) 3 :\ 


xf ; 
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. switch (wParam) 
{ . 


case IDM_DOIT: /* User hit the "Do it" menu item bf 
hdC = GetDC ChWnd) ; 
hRgn = CreakeELLIACGeRGi (20, 30, 80, 50) ; 
InvertRgn ChDC, hRgn) ; 
ReleaseDC (hWnd, hDC) ; 
DeleteObject (hRgn) ; 


; break ; 
[Other program lines] 
IsREcTEMPTY m Win 2.0 ~ mWin3.0 mWin3.1 
Purpose Determines if a rectangle has a height or width of zero. 
Syntax BOOL IsRectEmpty(LPRECT [pRect); 
Description Arectangle is empty if either the height or the width is zero. [= g erie : ic} sans 
Uses Useful in determining if the intersection of two rectangles defines a Do I! it 
rectangle (if they overlap), or if the current update rectangle is von ul 
ra empty. 
Returns BOOL. TRUE if the rectangle is empty, FALSE if not. 
See Also GetUpdateRect(), IntersectRect() 
Parameters 
lpRect . LPRECT: A pointer to a RECT data structure. 
Example Each time the “Do It!” menu item is clicked, an elliptical region is 


drawn on the screen, decreasing in size with each repetition. When 
either dimension of the rectangle defining the elliptical region 
becomes zero, the size is reset back to the initial state. (See Fig- Figure 11-54. IsRect- 
ure 11-54.) , 4 Empty() Example. 


x 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG \Param) 
{ 


HDC hoc ; 

static RECT rRect ; 

static int - nSize ; 

HRGN hRgn ; 

switch (iMessage) /* process windows messages */ 


case WM_| CREATE: 


nSize = 50 ; : 
SetRect (arRect, 10, 10, 10 + nSize, 10 + nSize * 2) ; 
break ; 


case WM_' COMMAND: | /* process menu items */ 
switch (wParam) . 
t 


case IDM_DOIT: /* User hit: the “Do it" menu item */ 


InvalidateRect (hwnd, NULL, TRUE) ; 
UpdateWindow (hWnd) ; ji erase client area */ 


hDC = GetDC ChWnd) ; 

hRgn = CreateELlipticRgnIndirect (&rRect) ; 
FILLRgn ChDC, hRgn, Geestoekobject CBLACK_! BRUSH) ; 
ReleaseDC ChWnd, hDC) ; 

DeleteObject (hRgn) ; 


nSize -= 10; /* shrink rectangle */ 
- . SetRect Caenect; 10, 10, 10 + nSize, . 
: 10 + nSize * 2) ; ie 
if (IsRectEmpty (&rRect)) 
{ 


nSize = 50; 
SetRect (erect, 10, 1b, 10 + nSize, 
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10 + nSize * 2) ; 


} 
break ; 
[Other program lines] 
LinEDDA Win2.0 Win3.0 m@Win3.1 
Purpose Draws a line with a custom drawing procedure. 
Syntax void LineDDA(int X/, int ¥/, int X2, int ¥2, FARPROC IpLineFunc, LPSTR ipData); 
Description LineDDA() calls a user-defined callback function for every point on a line between X/,Y/ and 
X2,Y2. The callback function can perform any calculation for each of these points. Normally, the 
calculation is performed to define the color of each point on the line. 
Uses . Custom line styles. aoe 
Returns No returned value. lee ogel eneric” a - 
See Also MoveTo(), LineTo() | Do lt! Quit 
Parameters 
‘X1 . int: The starting X position in logical coordinates. 
YI _ int: The starting Y position in logical coordinates. 
int: The ending X position in logical coordinates. 
¥2 ; int: The ending Y position in logical coordinates. 
lpLineFunc FARPROC: A procedure-instance address for the callback . 
function. This value is obtained with MakeProcInstance(). The Sseuqerreumercnceos = 
callback function name must also be listed in the EXPORTS Figure 11-55. LineDDA() ‘ 
.section of the program’s .DEF definition file. Example. 
lpData LPSTR: A pointer to any data that should be passed to the 
a 4 - Callback function. This pointer is usually used to pass tl the device context handle. 
Callback Function 
The callback function must be defined in the following format: 
void FAR PASCAL LineFune (int X, int Y, LPSTR /pData) ; 
The callback function is called for every point on the line each time the.X and Y position on the. 
line and the /pData value are passed to the callback function. No line is drawn unless points are 
drawn from within the callback function: 
Example This program draws a line when the user clicks the “Do It!” menu item, as shown in Figure 11-55. 


~ The line is drawn with a custom DDA function that changes the color of the line as a function of 


the coordinates of each point. Although not visible in the figure, this line changes from blue to 


_ brown from top left to bottom right when it is viewed on screen. 


The example code only shows the WndProc() and DDA functions. In addition, the program 
must include a function declaration in the header file, and list the “LineProc” function name in 
the EXPORTS section of the .DEF definition file. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


~ HOC 
FARPROC 


switch CiMessage) 
{ 


hDC ; 
lpfnLine ; 


/* process windows messages */ 


case WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
InvalidateRect (hWnd, NULL, TRUE) ; 
/ UpdateWindow (hWnd) ; - /* erase client area */ 

hDC = GetDC ChWnd) >; 
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. . ' 
lpfnLine = MakeProcInstance (LineProc, ghInstance) ; 
LineDDA (10, 10, 150, 150, LpfnLine, 
CLPSTR) CDWORD) hDC) ; . 
FreeProcInstance (tpfnbine) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT; 
DestroyWindow (hwnd) ; 
break ; 
} 
_ break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; : 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; 
} 


/* callback function */ 
void FAR PASCAL LineProc (int X, int Y, LPSTR LpData) 
{ . 


SetPixel (CHANDLE) (DWORD) LpData, X, Y, 
RGB (X % 255, Y % 255, (X + Y) % 255)) ; 
SetPixel CCHANDLE) (DWORD) LpData, X, Y + 1, \ 
RGB (X % 255, Y % 255, (X + Y) % 255)) 
SetPixel CCHANDLE) (CDWORD) LpData, X, Y + 2, 
RGB (X % 255, ¥ % 255, (X + Y) % 255)) ; 


Se 


} 
‘LinETo | aWin20 mWin30 mWin3l 
Purpose Draws a line from the current location to a new point. 
Syntax - BOOL LineTo(HDC DC, int.X, int Y); . ; — — 
Description Used with MoveTo() to draw lines. MoveTo() moves the start- Ke . ge e n e ti c ~ mel 
ing point for the next line to a new location without drawing. Do it! Q uit 
LineTo() draws a line to X,Y using the currently selected pen. 9 —= : 
Uses LineTo() is convenient when a series of connected linesareto § 
be drawn. Windows does not provide a single function for draw- 
ing isolated lines such as Line (hDC, X1, YI, X2, Y2). You can 
PP x create such a function by combining MoveTo() and LineTo(). 
Sire __ See the example under MoveTo(). . 
Returns" BOOL. TRUE if the line was drawn, FALSE on error. 
See Also MoveTo(), GetCurrentPosition(), CreatePen(), 
~ SelectObject(), PolylineQ) 
Parameters ; NPE 
hDC HDC: The device context handle. Actaldivaas Lina) 
X : int: The logical X coordinate for the end of the line. The start of 
the line is either the end position from the last Het ot) call or . 
the position obtained by calling MoveTo(). : a 
Y ' int: The logical Y coordinate for the end of the line. 
Example . This example paints two connected blue lines in the client area, as shown in Figure 11-56. 
Pigs FAR PASCAL WndProc CHWND hind, unsigned iMessage, WORD wParam, LONG L\Param) 
PAINTSTRUCT = ps3 : 
HPEN ; hPen ; 
switch (imMessage) /* process windows messages */ 
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{Other program lines] 


MAKEPOINT 


Purpose 
Syntax 
Description 


#define MAKEPOINT(L) 


‘case WM_PAINT: 


BeginPaint (hWnd, &ps) ; 

hPen = CreatePen “(PS_ DASHDOT, 2, RGB (0, 0, 255)) ; 
SelectObject (ps.hdc, hPen) ; 

MoveTo (ps.hdc, 10, 100); 

LineTo (ps.hdc, 40, 10) ; 

LineTo (ps.hdc, 70, 100) ; 

EndPaint (hWnd, &ps) ; 

DeleteObject (hPen) ; 

break ; 


f Win 2.0 Win3.0 mWin3.1 
’ Converts from a DWORD value to a POINT structure. 
POINT MAKEPOINT(DWORD dwinteger); 


Windows functions frequently encode position values in 32- bit DWORDs. MAKEPOINT() is a 
macro that converts from the DWORD format to a POINT structure. The macro and point struc- 
ture are defined in WINDOWS.H as follows: 


C*CCPOINT FAR *)&C(L))) 


typedef struct tagPOINT 
{ 


int x; 
int y; 
} POINT; 


typedef POINT 
typedef POINT NEAR 
typedef POINT FAR 


Uses 


Returns 
See Also 


Parameters 
dwInteger 


Example 


MoveTo 


Purpose 
Syntax 
Description 


Uses 


Returns 


See Also 


Parameters | 


hDC 
Xx 


- before line drawing begins. The following example shows the 


int: The logical X coordinate. 


*PPOINT; 
*NPPOINT; 
*LPPOINT; 


The point structure is simpler to work with if you need to extract either the X or Y value sepa- 
rately. 


A pointer to a POINT data structure. 


_ MoveTo(), LineTo(), MAKEPOINT() 


DWORD: A 82-bit value with the low-order word containing the X coordinate value, and the high- 


order word containing the Y coordinate value. 


See the example under the GetCurrentPosition() function description. 


Win2.0 . eWin3.0 mw Win3l 
Moves the current position to a new location, ready to draw a line, 
DWORD MoveTo(HDC DG, int X, int Y); . 


Used with LineTo() to draw lines. MoveTo() moves the starting point for the next line to a new 
location without drawing. LineTo() draws a line to.X,Y using the currently selected pen. 


In order to position the start of the next line, MoveTo() is used 


creation of a typical line drawing function that combines 
MoveTo() and LineTo. 

DWORD, the previous logical position. The low-order word con- 
tains the X position. The high-order word contains the Y posi- 
tion. 


LineTo(), CreatePen(), SelectObject(), Polyline() 


HDC: The device context handle. 


Figure Il 57, Moveol d 
Example. 
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Y int: The logical Y coordinate. 
Example This example, which is illustrated in Figure 11-57, creates a a function called Line() that draws 
lines using the currently selected pen and allows both the starting point and ending point of the 
line to be specified in one function call. The function is called twice to draw two blue lines on the 
client area. if 
The header file must also include the function declaration for the Line() function. 
Pate FAR PASCAL WndProc C(HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


PAINTSTRUCT ps ; 
HPEN hPen ; 
switch (iMessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hPen = CreatePen “(PS_| DASHDOT, 2, RGB (0, 0, 255)) ; 
SelectObject (ps.hdc, hPen) ; 
Line (ps.hdc, 10, 10, 60, 10) ; 
vet ‘ Line (ps.hdc, 10, 50, 60, 50) ‘ 
EndPaint (hWnd, &ps) ; 
DeleteObject (hPen) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
case IDM_QUIT: , /* send end of application message x] 
DestroyWindow ChWnd) ; 
break ; 
} ; ep 
break ; ; - 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 2 
return (OL) ; 
} , *S 


1 re 


void Line (HDC KDC, int X1, int Y1, int X2, int Y2) 
{ 


MoveTo C(hDC, X1, Y1) ; 
LineTo C(hDC, X2, Y2) ; 


} 

OFFSETCLIPRGN | 2 m@Win2.0 mWin30 mWin31 

Purpose | Moves the clipping region. 

Syntax int OffsetClipRgn(HDC hDC, int.X, int Y); 

Descriptior _ The clipping region limits the area on the device that will be painted by GDI function calls, such 
. as LineTo() and Rectangle(). OffsetClipRgn() allows an existing clipping region to be moved toa 

; new location on the device context. 5 
Uses Useful in scrolling operations with graphics images. 
Returns int, the type of region created. This can be any of the region types in Table 11- a1. 


COMPLEXREGION The new region has overlapping borders. 


ERROR | No new region was created. 
NULLREGION The new region is empty. . 
SIMPLEREGION ‘The new region does not have overlapping borders. . 


Table 11-21. Region Types. — - ; a 


“ 


‘ \ 


Phy . 499 


WINDOWS AP! BIBLE - 


| See Also 


SelectClipRen() 
Parameters 
hDC HDC: The device context handle. 
xX ; int: The amount to offset the region in the.X direction, mea- 
sured in logical units. 
| ror ‘int: The amount to offset the region in the KE direction, mea- 
sured in logical units. 
Example This example creates a rectangular clipping region, as shown 


painted when the Rectangle() function is called. OffsetClip- 
Rgn() is used to move the clipping region down and to the. 


in Figure 11-59. The clipping region limits the area that is Figure 11-59. OffsetClip- 
Rant rere 74 


right. The second call to Rectangle() is limited by this new, repositioned clipping region. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ‘ : i 


PAINTSTRUCT ps; 
HRGN hRgn ; 


switch (iMessage) 
{ ot 


/* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hRgn = CreateRectRgn (10, 10, 60, 40) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockObject (BLACK _BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 300) ; 
OffsetClipRgn (ps.hdc, 20, 20) ; 
Rectangle (ps.hdc, 5, 5, 500, 500) ; 
EndPaint ChWnd, &ps) ; 
Deletedbject chRgn? 7 


break ; 

[Other program lines] . - 
OrrserRECT mWinl.0 @ Win 39 - ewin3.l 
Purpose Shifts a rectangle in the X and Y directions. ome Be Pee, 
Syntax void OffsetRect(LPRECT [pRect, int X, int Y); T° 7 I 9 eneric. wake ze 
Description This is a convenient function for changing the location of a rect- | Dott! Quit. | 

~ angle without changing its size. InflateRect() changes thesize § Sees 

without changing the location. | 
Uses Frequently used in creating dinning regions, © 
Returns No returned value (void). ; i oy ee 
See Also SelectClipRgnQ), CreateRectRgn(), Createlitien0, Figure 11-60. OffsetRect() 
InflateRect() Example, 

Parameters ~ 
lpRect LPRECT: A pointer to a RECT data structure holding the dimensions of the Rana to offset. 
X int: The amount to offset the rectangle’s position horizontally. 
Y int: The amount to offset the rectangle’s position vertically. 
Example ‘In the example shown in Figure 11-60, a complex region is created by combining two regions 


using the logical RGN_XOR operation. The two regions are both based on the same rectangular 


' size. In the first case, an elliptical region hRgn/ is made from the rectangle’s dimensions. A . 


second rectangle is created by copying the first, and then offsetting the rectangle’s coordinatés 
to the right 25 logical units, The two regions are combined using CombineRgn(), and then used as 
the clipping region. Only the areas S within the clipping region are e painted When a large, gray . 
rectangle is drawn. ; 
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long FAR PASCAL WndProc CHWND hind, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


PAINTSTRUCT ps; 

HRGN hRgni, hRgn2, hRgnComb ; 

RECT rRect1, rRect2 ; 

switch CiMessage) /* process windows messages */ 
¢ 


case WM_PAINT: - 
BeginPaint (hWnd, &ps) ; 
SetRect (&rRecti, 10, 10, 60, 40) ; 
CopyRect (C&rRect2, BrRect1) + 
OffsetRect (&rRect2, 25, O) ; 
hRgni = ceguteECCipeqcnHInalreck CarReett) ; 
hRgn2 = CreateRectRgnindirect (&rRect2) ; 
hRgnComb = CreateRectRgn (1, 1, 2, 2) ie initialize */ 
CombineRgn ChRgnComb, hRgn1, hRgn2, REN XOR) ; 
DeleteObject (hRgni) ; | 
DeleteObject ChRgn2) ; 


SelectClipRgn (Cps.hdc, hRgnComb) ; 

SelectObject (ps.hdc, GetStockobject CLTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 500) ; 

EndPaint (hWnd, &ps) ; 

DeleteObject (hRgnComb) i 


4 _ break ; 
[Other program lines] 
OFFSETRGN . | | Win2.0 mWin3.0 eWin3.l 
Purpose Moves a region. . 
Syntax int OffsetRgn(HRGN hFgn, int X, int Y); 
Description This is identical to OffsetRect(), except a region is offset instead of a rectangle. 
Uses Used i in creating clipping regions composed of similar shaped objects at different locations. 
Returns int, the pe of region created. This can be any of the region types listed in Table 11-22. 
COMPLEXREGION a é Then new region has Receaae borders. 
ERROR = _ Nonew region was created. 
NULLREGION , The new region is empty. 
SIMPLEREGION The new region does not have overlapping borders. 


Table 11-22. Region Types. 


‘See Also CreateEllipticRgn(), CreateRectRgn(), CombineRgn() 
Parameters ae 7 7 | 

hRgn HRGN: The handle of the region to offset. . 

x int: The amount to offset the region’s position horizontally. 

Y int: The amount to offset the region's position vertically. 
Example This example creates a complex clipping region by combining 


two elliptical regions using the logical RGN_XOR operation. Saucers 
(See Figure 11-61.) The second region is created by copying Figure 11-61. OffsetRgn{) 
the first, and then offsetting it to the right by 25 logical units. Example. . 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ ; 
PAINTSTRUCT ps ; 
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HRGN hRgn1, hRgn2, hRgnComb ; 


RECT _rRect ; 
switch (iMessage) _ /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SetRect (&rRect, 10, 10, 60, 40) ; 
hRgnt = Sree ere ele anne tec CarRect) ; 


hRgn2 = CreateRectRgn (1, 1, 2, 2) ; a ‘inteietize */ 
CombineRgn ChRgn2, hRgnt, NULL, RGN_ COPY) ; /* copy */ 
OffsetRgn ChRgn2, 25, 0) ; /* move rgn 2 to right */ 


hRgnComb = CreateRectRgn te 1, 2, 2) ;/* initialize */ 
CombineRgn (hRgnComb, hRgnt, hRgn2, RGN_XOR) ; 
DeleteObject ChRgn1) ; 

DeleteObject ChRgne2) ; 


SelectClipRgn (ps.hdc, hRgnComb) ; 

SelectObject (ps.hdc, GetStockobject (LTGRAY —BRUSH)) ; 
Rectangle (ps.hdc, 5, 5, 500, 500) ; 

EndPaint (hWnd, &ps) ; 

DeleteObject ChRgnComb) 7 


break ; 
[Other program lines] 
PaINnTRGN Win2.0 wWin30 ms Win3.1 
Purpose Paints a region with the currently selected brush. 
Syntax | BOOL PaintRgn(HDC ADC, HRGN hRgn); —- if RENE 
Description This function is similar to FillRgn(), except the currently se- Do i Quit 
lected brush of the device context is used to paint the region, § ——— 
rather than specifying the brush handle in the function call. 
Uses ~ Painting irregular areas. 
Returns BOOL. TRUE if the region is painted, F FALSE on error. 
See Also FillRgn() 
Parameters _ 
hDC .° HDC: The device context handle. The currently selected brush 
aoe of the device context is used to paint the region. z= oe 


Example This Sainte creates a region by combining two elliptical re- Example. 
gions. The region is then painted with a hatched brush, as 
shown in Figure 11-62. 
oe FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


PAINTSTRUCT ps; 

HRGN hRgnt, hRgn2, hRgnComb ; 

HBRUSH -hBrush ; 

switch (iMessage) /* process windows messages */ 
{ . 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; ° 
hRgni = CreateElLlipticRgn (10, 40, 90, 70) ; 
hRgn2 = CreateEllipticRgn (40, 0, 70, “100) i. 
hRgnComb.= CreateRectRgn (1, 1, 2, 2) pl* initialize */ 
CombineRgn (ChRgnComb, hRgnt, hRgn2, RGN_OR) ; 
DeleteObject ChRgn1) ; : 
DeleteObject ChRgn2) ; 


SelectClipRgn (ps.hdc, hRgnComb) ; 

hBrush = Creacevetener den CHS_! DIAGCROSS, 
RGB (0, 0, 255)) ; 

SelectObject (ps.hdc, hBrush) ; 
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PaintRgn (ps.hdc, hRgnComb) ; . 
EndPaint ChWnd, &ps) ; 
DeleteObject ChBrush) ; 
DeleteObject ChRgnComb) ; 


break ; 
[Other program lines] 
PIE @Win2.0 mWin30 mWin3.1 
Purpose Draws a pie-shaped wedge. eat at 
Syntax BOOL Pie(HDC hDC, int X/, int Y1, int X2, int Y2,intX3,intY3, — ‘gen eric: [x a 
int X4, int Y4); [Doll Quit | it! ‘Quit. =) 
Description The pie-shaped wedge is drawn with the currently selected pen = —————-__— 
and filled with the currently selected brush. The outer circleof § : 
the pie is defined by the bounding rectangle of an ellipse. The 
starting and ending points are defined by lines from points 
X3,¥3 and X4,Y4, to the center to the bounding rectangle. 
The height and width must be smaller than 32,767 logical 
units. 
Uses Making pie charts. 
Returns BOOL. TRUE if the shape was drawn, FALSE on error. 
See Also ChordQ), ArcQ) —————— 
Parameters Figure 11-63. Pie() Example. 
hDC HDC: The device context handle. 
xl int: The logical X coordinate of the upper left corner of the bounding rectangle. 
Y] int: The logical Y coordinate of the upper left corner of the bounding rectangle. 
X2 int: The logical X coordinate of the lower right corner of the bounding rectangle. 
Y2 int: The logical Y coordinate of the lower right corner of the bounding rectangle. 
X3 int: The logical X coordinate of the starting point of the pie slice. 
—¥3 int: The logical Y coordinate of the starting point of the pie slice. 
X4 int: The logical X coordinate of the ending point of the pie slice. 
Y4 . int: The logical Y coordinate of the ending point of the slice. 
Example This example, which is shown in Figure 11-63, paints a pie-shaped slice with the Pie() function. 


In addition, the bounding rectangle is painted, and the locations of the four points that define the 
pie are numbered, 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


PAINTSTRUCT ps; 
HBRUSH hBrush ; 
HPEN hPen ; 
- switch CiMessage) /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hBrush = CreateHatchBrush (HS_DIAGCROSS, 
RGB (O, 0, 255)) ; 
SelectObject (ps.hdc, hBrush) ; 
hPen = CreatePen (PS_SOLID, 3, RGB (255, 0, 0)) ; 
SelectObject (ps.hdc, hPen) ; 

_ SetBkMode (ps.hdc, TRANSPARENT) ; t. 
Pie (ps.hdc, 10, 10, 100, 100, 0, 70, 70, O) ; 
TextOut (ps.hdc, 10, 10, "1", 1) >; 

TextOut (ps.hdc, 100, 100, “2", 1) ; 
TextOut (ps.hdc, 0, 70, "3", 1); . 
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TextOut (ps.hde, 70, 0, "4", 1) ; 

SelectObject (ps. hde; Garstockouect CNULL_BRUSHD) ; 
‘SelectObject (ps.hdc, Geretockob test ,PLAcK. PEN)) ; 
DeleteObject ChBrush) ; 

DeleteObject (hPen) ; 

Rectangle (ps.hdec, 10, 10, 100, 100) ; 

EndPaint ChWnd, &ps) ; 


break ; 

[Other program lines] 

‘POLYGON | | | @Win2.0 @Win30 w#Win3l 

Purpose - Draws a. polygon, 

Syntax BOOL Polygon(HDC hDC, LPPOINT ipPotnts, int nCount); . 
Description |§ Apolygonisaclosed figure composed of three or more straight lines. The polygon is drawn on the 
: device context using the currently selected pen and brush and the current polygon filling mode. 
Uses . Creating complex drawings. 

Returns ‘BOOL. TRUE if the function drew the polygon, FALSE on error. 

See Also PolyPolygon(), SelectObject(), DeleteObject0), 

; ia lace 
Parameters 
hDC HDC: The device context handle. 


lpPoinis _ LPPOINT: A pointer to an array of nCount or more points that 
. will define the polygon. If the first and last points do not coin- 

cide, the function will draw a line between them to close the 

polygon. The polygon lines may cross, creating a complex poly-_ 

gon. See SetPolyFillMode() to define how these objects are 


filled. 
nCount - int: The number of points in the lpPotits array to read. <TEIERETS SEI 
Example In this example, shown in Figure 11-64, a polygon is drawn us- Figure I - 64, Polygon ) 
ing a pen created with CreatePenIndirect(). - _ Example. 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ : : 


PAINTSTRUCT . ps ; 
HPEN - © hPen ; 
LOGPEN — LP ; 
POINT pPenWidth ; 
POINT paorsy C3 = (10, 100; "45, 5, 50, 50, 90, 0, 
60, 110) ; 
switch (iMessage) '/* process Windows messages */ 
{ 


case WM_PAINT: 

BeginPaint (hWnd, ‘&ps) ; 
pPenWidth.x = 2; : 
LP. lopnStyle = PS_DASH ; 
LP. lLopnWidth = pPenWidth ; 

= LP. lopnCotor = RGB (0, 40, 50) ; 
hPen = CreatePenIndirect (&LP) ; 
SelectObject (ps.hdc, hPen) ; 
Polygon (ps.hdc, pArray, 5) ; 
EndPaint ChWnd, &ps) ; 
DeleteObject ChPen) ; 


break ; 
[Other program lines] | 
POLYLINE __ vo | : as me Win20 mWind0 mWin3l © 
Purpose . “Draws a line with multiple segments. *2 , 
Syntax BOOL eet hDC, LPPOINT lpPoints, int nCount); 
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Description 


Uses. 

. Returns 
See Also 
Parameters 
hDC 


lpPoints 


nCount 


Example 
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This function is equivalent to calling MoveTo(), followed by a 
series of one or more calls to LineTo(). Each of the line seg- 
ments drawn is connected to the last. The: line | is drawn with 
the currently selected pen. 

Drawing irregular lines which are connected. 

BOOL. TRUE if the line’ was drawn, FALSE on error. 


MoveTo(), LineTo(}j CreatePen(), SelectObject() 


HDC: The device context handle. 
LPPOINT: An array of at least Count POINT data structures 
defining the line to be drawn. 


int: The number of points in the /pPoints array. Must be two or 
more points. 


This example, which is shown in Figure 11-65, uses Polyline() 
to efficiently draw a line with three segments on the client 
area. : 


Figure 11-65. Polyline() 
Example. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


PAINTSTRUCT ps ; 


POINT pLine Cl = (10, 10, 30, 90, 50, 30, 70, 100? ; 


HPEN hPen ; 


switch wibsseage? 
{ 


/* process windows messages */ 


case we PAINT: 
BeginPaint (hind, &ps) ; 
hPen = CreatePen (PS_SOLID, 3, RGB (0, 0, 255)) ; 
SelectObject (ps.hdc, hPen) ; 
Polyline (ps.hdc, pline, 4) ; 
EndPaint. (hwnd, &ps) ; 
DeleteObject (hPen) ; 


, break ; 
[Other program lines] 
POoLYPOLYGON OWin20 @Win30  eWindt 
Purpose ~ Draws one or more polygons, . 
Syntax BOOL PolyPolygon(HDC DC, LPPOINT /[pPoints, LPINT IpPolyCounts, | int nCount); 
Description This function allows any number of polygons to be drawn with one function call. The polygons are 
drawn with the currently selected pen and brush, If the lines of the polygons cross, interior re- 
gions are drawn based on the current polygon filling mode. 
Uses An efficient way to draw a series of enclosed areas. 
| Returns BOOL. TRUE if the polygons were drawn, FALSE on error. 
See Also -Polygon(), SetPolyFillMode() 
Parameters - 
hDC HDC: The device context handle. ' 
lpPoints _LPPOINT: A pointer to an array of POINT data structures that contain the vertices of the poly- 
_ gons. There must be at least as many points as specified by the Jp PolyCounts array. The points for 
each independent polygon must be together in the array. 
lpPolyCounts LPINT: An array of integers that contains the number of points in lpPoints to assign to each 
>” successive polygon. 
nCount int: The number of elements in the lpPolyCounts array (not the number of total points), 
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Example __ This example, as shown in Figure 1 1-66, paints two polygons in one call to PolyPolygon(). The first . 
is a triangle, defined by four points. The first and last points of the four are the same, so the region 
is closed. The second polygon is defined by five points, but the first and last points are not the 
same. PolyPolygon() does not close the region automatically. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
cg 


PAINTSTRUCT ps; 
POINT pline CJ = (10, 10, 30, 90, 50, 30, 10, 10, 
70, 0, 60, 50, 100, 100, 90, 25, 70, 120} ; 
int pPolygons CJ = (4, 5} ; . 
HPEN hPen ; 
HBRUSH hBrush ; 
switch (iMessage) /* process windows messages */ 
t “ 


case WM_PAINT: . M a 
BeginPaint (hWnd, &ps) ; ; 
hPen = CreatePen “CPS SOLIO, 3, RGB tas 0, 255)) ; 
hBrush = CreateHatchBrush CHS. ~DIAGCROSS, 

RGB (255, 0, 0)) ; 
SelectObject (ps. hde, hPen) : 
SelectObject (ps.hde, hBrush) ; 
- PolyPolygon (ps.hdc, pLine, pPolygons, 2); 
_EndPaint (hWnd, &ps) ; 
DeleteObject Chpen) ; 
- DeleteObject Cherian 3 


break ; 
[Other program lines] 
PrinRecT 
Purpose Determines if a point is within a rectangular area. 
Syntax BOOL PtInRect(LPRECT [pRect, POINT Point), 
Description This function typically is used to determine if the mouse cursor is within a certain area on the 
client region. 
Uses. Used in paint programs, and other programs that track the mouse location. 
Returns BOOL. TRUE if the point is within the rectangle, FALSE if not. 
See Also Ptinkegion(), PtVisibleQ) 


In Rect 


Figure 11-66. PolyPolygonQ) Figure 11-67. PtinRect()’ Figure il- 1-68. “PlinRegion( ) 
Evanple. Laample. _ Example. 
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Parameters 
lpRect 


Point 
Example 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ; , 
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LPRECT: A pointer to a RECT data structure holding the dimensions of the rectangle to check. 
POINT: A POINT data structure. 
This example paints a rectangle in the client area, see Figure 11-67, If the user clicks the left 


_mouse button within the rectangle, “In Rect” is flashed. Clicking outside of the rectangle results 


in “Not Inside” being flashed. The screen is painted when the user releases the mouse button, 
erasing the message as the rectangle is repainted. 


‘ 


PAINTSTRUCT ps; 

HDC hoe ; 
static RECT rRect ; 
POINT pCursor ; 


switch (iMessage) 
{ 


/* process windows messages */ 


case WM_CREATE : 
SetRect (&rRect, 10, 10, 100, 100) ; 
break ; 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, rRect.left, rRect.top, rRect.right, 
rRect.bottom) ; 
EndPaint (hWnd, &ps) ; 
break ; 
case WM_LBUTTONDOWN: : 
pCursor = MAKEPOINT (tParam) ; 
hDC = GetDC (hWnd) ; 
if (PtInRect (BrRect, peursoi)) 
TextOut (hDC, 10, 50, “In Rect", 7) ; 


else 
TextOut ChDC, 10, 50, "Not Inside", 10) ; 
ReleaseDC (hWnd, hdd ; 
break ; 
case WM_ LBUTTONUP: 
InvalidateRect ChWnd, NULL, TRUE) ; 
UpdateWindow ChWnd) ; 


: break ; 

[Other program lines] 

PrINREGION mWin2.0 mWin30  mWin3l 

Purpose Determines if a point is within a region. 

Syntax BOOL PtinRegion(HRGN hFgn, int.X, int Y); 

Description This function is similar to PtinRect(), except a region is used in place of a rectangle. It is typically 
used in conjunction with the mouse cursor to determine if the location of the cursor is within a 
region. 

Uses Used in painting programs, For example, if the cl cursor is within a region, a flood fill serine may 
be possible. 

Returns BOOL. TRUE if the point is within the region, FALSE if not. © 

See Also PtInRect(), PtVisibleQ 

Parameters . 

hRgn HRGN: A handle to a region. 

Xx int: The logical X coordinate of the point. 

Y int: The logical Y coordinate of the point. 

Example 


This example paints an irregular shape using a clipping region, as illustrated in Figure 11-68, 
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| When the user clicks the left mouse button inside the client region (WM_LBUTTONDOWN mes- 
sage), the program checks whether the mouse cursor is within the region. If so, it shows the 
message “In Region” until the mouse button i is released. 


long FAR PASCAL WndProc CHWND hwnd, unsigned iMessage, WORD wParam, LONG tParam) 
{ 


_ PAINTSTRUCT . ps; 
HDC hoc ; 
“static HRGN hRgn ; 
POINT pArray C5] =. (10, 10, 50, 40, 90, 20, 60, 0, 
ae 0, 20) ; 
POINT pCursor ; 
switch (iMessage) /* process windows messages */ 


case WM_CREATE : 
hRgn = CreatePolygonRgn (pArray, 5, WINDING) ; 
break ; : 

case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockobject CLTGRAY_BRUSH)) ; 
Rectangle (ps.hdc, 0, 0, 500, 500) ; /* paint gray w/ 

‘ EndPaint ChwWnd, &ps) ; 

break ; 

case WH_ LBUTTONDOWN: 
pCursor = MAKEPOINT ‘(tParam) ; 
hDC = GetOdC ChWnd) ; 
if CPtInRegion Chior pCursor.x, pCursor. y)) 

TextOut (hoc, 10, 50, “In Region", 9) ; 
else 
TextOut ChDC, 10, 50, "Not inatee:? 10) ; 

ReleaseDC ChWnd, hDC) ; 
break ; 

case WM_ LBUTTONUP: 
InvalidateRect Chitnd, nUEbe TRUE) ; 
‘UpdateWindow (hind) ; 


break ; Bhd! 
case WH COMMAND: /* process menu items */. 

switch (wParam) . 

t 

case IDM_QUIT: /*- send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 

> 

break ; ‘ Ve 


case WA DESTROY: /* stop application */ 
DeleteObject ChRgn) ; Xs ae oe 
PostQuitMessage (0) ; 
break ; 
default: /* default windous message processing */ 
return DeflindowProc ChWnd, anesencee uParan, Param? 


d 
return (OL) ; 


> 

Prvisiple | . eWin20 wWin30 mWin3.1 

Purpose Checks whether a point is within the clipping region. 

Syntax BOOL PtVisible(HDC ADC, int X, int Y); 

Description This function checks whether the given point is within the clipping peainy set for the device 
. context. — 

Uses . Used most frequently to check if the 1 mouse pointer or.caret nosttbon is within the area that will 

‘ultimately become painted.. 
Returns BOOL. TRUE if the point is within the clipping region, FALSE if not. 
See Also PtInRegion(), sauna SelectClipRgn() 
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waadisiie Flgenericl= = 
HDC: The device context handle that has a clipping region IGENenit] vy {*~ 
selected. . 
int: The logical X coordinate of the point to check. 
int: The logical Y coordinate of the point to check. 
This example, which is illustrated in Figure 11-69, paints an 
elliptical area by setting an elliptical clipping region, and then 
painting over it with a gray brush. If the user clicks the left 
mouse button within the clipping region, the word “Visible” 
appears inside the ellipse. Otherwise “Not Visible” appears. 
The printing must be within the ellipse, as this is the clipping Figure 11-69. PtVisible( ) 
area and text outside of it would not be printed. Example. 

Note that the clipping area must be specified every time 


. the device context handle is fetched. In this example, setting the clipping region within the 


WM_PAINT logic is effective only until the EndPaint() function is called. 


long FAR PASCAL WndProc (HWND hind, unsigned iMessage, WORD wParam; LONG LParam) 
Pi 


PAINTSTRUCT .. ps; 

HOC ; hoc ; 

static HREN hRgn ; 

POINT eCursor ; 

switch CiMessage) | /* process windows messages w/ 


2 


case WM_CREATE : 
hRgn = CreateElLlipticRgn (20, 20, 100, 60) ; 
break ; 
case WA_PAINT: 
BeginPaint Chiind, &ps) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockObject CLTGRAY eRUsHD? ; 
Rectangle (ps.hdc, 0, 0, 100, 100) ; 
EndPatnt Chund, SRS)? 
‘break ; 
case WA_LBUTTONDOWN: 
pCursor = MAKEPOINT (lParam) ; 
hOC = GetbC (hWnd) ; 
SetectClipRgn ChDC, hRgn) ; 
1f CPtVisible (hoc, pCursor.x, pCursor. y)) 
TextOut (hOC, 30, 30, “Visible”, 7) ; 
else 
; TextOut (hOC, 30, 30, “Not Visible", 11) ; 
1 ReteaseDC (hWnd, hDC) a ; 
break; - 
case WA _LBUTTONUP: 
InvalidateRect Chund, NULL, TRUE) ; 
UpdateWindow (hwnd) ; 


break ; 
case WH_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case 1DH Quit: /* send aiid of application message */ 
DestroyWindow ChwWnd) ; 
break ; 
} 
- break ; ; : 
case WM_DESTROY: /* stop application */ 


Deletedbject ChRgn) 
PostQuitMessage (0).. 
break ; 

default: . -/* default windows message processing */ 
return DefWindowProc Chiind, iMessage, eraras, (Param) ; 


w we 


return ¢: | re 
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RECTANGLE 
Purpose - 
Syntax 
Description 


Uses - 


Returns © 
See Also 
Parameters 
hDC 


¥2 
Example 


& Win 2.0 Win3.0. @ Win 3.1 


Draws a rectangle. 


‘BOOL Rectangle(HDC ADC, int X/, int Y/, int X2, int ¥2); 


The rectangle is drawn with the currently selected pen for the border, and filled with the current 


_ brush. The width and height must not exceed 32,7@7 units. 


Painting rectangular areas. To draw the outline, select the stock object NULL_BRUSH. To fill the ~ 
area, but not draw the border, select the stock NULL_PEN. 


’ BOOL. TRUE if the rectangle was drawn, FALSE on error. 


SelectObject() 


HDC: The device context handle. — 

int: The logical X coordinate of the upper left corner of the rectangle. 

int: The logical Y coordinate of the upper left corner of the rectangle. 

int: The logical X coordinate of the lower right corner of the rectangle. 

int: The logical Y coordinate of the lower right corner of the rectangle. 

This example paints a rectangle in the client area with a hatched brush, as shown in Figure 11-70. 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
4 


" PAINTSTRUCT ps ;. 
HPEN hPen ; 
HBRUSH hBrush ; 


oS 


“, 


“\ switch CiMessage) 
{ 


/* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hPen = CreatePen (PS SOLID, 3, RGB (0, 0, 2552) | 
hBrush = CreateHatchBrush CHS __DIAGCROSS, 
RGB (255, 0, 0)) ; 
SelectObject (ps hde, hPen) 3 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 20, eed 100, 70) ; 
EndPaint (hWnd, Eps) ; > 
DeleteObject (hPen) ; 
ee ChBrush) ; 
break ; 


{Other program lines] 


ReEcTINREGION ca | Win 2.0, Wind mw Win3d 


Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 
Parameters 
hRgn 
lpRect 
Example 


Checks whether a rectangle is within a region. 


~ BOOL RectIinRegion(HRGN hRgn, LPRECT ‘IpRect); 


The rectangle is considered to be within the region if any point falls within the moun of the 
region. 


Used to determine if there is S any reason to drawa rectangle, as it may fall outside of the dinning 
region. 


BOOL. TRUE if any part of the ectanile falls inside of the region, FALSE if not. 
RectVisible() 


“P 
HRGN: A handle for a region. 
LPRECT: A pointer to a RECT data structure holding the dimensions of the rectangle. 


_ This example checks to see if the rectangle is within the clipping region before drawing it. The 


clipping region is elliptical and ultimately eliminates all but the upper left corner of Me rect- 
angle. (See Figure 11-71.) 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


{ . 
PAINTSTRUCT ps ; 
HRGN hRgn ; 
RECT rRect ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
hRgn = CreateEllipticRgn (10, 10, 100, 80) ; 
SelectClipRgn (ps.hdc, hRgn) ; 
SelectObject (ps.hdc, GetStockObject (LTGRAY_BRUSH)) ; 
SetRect (&rRect, 50, 50, 100, 100) ; 
if (RectInRegion (hRgn, &rRect)) 
Rectangle (ps.hdc, rRect.left, rRect.top, 
rRect.right, rRect.bottom) ; 
EndPaint (hWnd, &ps) ; 
DeleteObject ChRgn) ; 
break ; . =a 

[Other program lines] ; 

RECcTVISIBLE Win2.0 Win3.0 Wind 

Purpose Checks to see if a rectangle has points within the current clipping region. ; 

Syntax BOOL RectVisible(HDC hDC, LPRECT lpRect); 

Description Clipping regions are created with SelectClipRgn(). Once set, only points within the clipping re- 
gion are painted. RectVisible() checks that at least one point on a rectangle falls within the 
clipping region. 

Uses Checking whether the rectangle is visible can save time on screen refresh cycles where the clip- 
ping region or rectangle change location. There is no point in painting the rectangle, or shape 
bounded by a rectangle (arc, chord, pie, ellipse), if all of the shape falls outside of the current 

' clipping region. 

Returns BOOL. TRUE if part of the rectangle falls within the clipping region, FALSE if not. 

See Also RectInRegion(), SelectClipRgn()\ 

Parameters 

hDC HDC: The device context handle. 

lpRect LPRECT: A pointer to a RECT data structure containing the dimensions of the rectangle. This 
can also be the bounding rectangle used to paint a chord, are, pie, or ellipse. 

Example This example, which is shown in Figure 11-72, creates a rectangular clipping region. Before paint- 


Slatetetetelet 


Example. 


Figure 11-70. Rectangle() Figure 11-71. RectInRegion() 


ing a filled ellipse, the program checks that the bounding rectangie of the ellipse will be visible 


(within the clipping region). 


Me a 
wk 


Quit 


Example. , Example. 
511 


WINDOWS API BIBLE 


long FAR PASCAL WndProc (HWND hilnd, unsigned iMessage, WORD wParam, LONG lParam) 
€ , ; 7 = 


-PAINTSTRUCT ps ; 
HRGN hRgn ; 
RECT rRect ; 
HBRUSH hBrush ; 


switch (iNessage) 
{ 


case WM_PAINT: 


/* process windows messages */ 


BeginPaint ChWnd, &ps) ; 


hRgn = CreateRectRgn 


«10, 10, 100, 80) ; 


SelectClipRgn (ps.hdc, hRgn) ; . 


hBrush = 


CreateHatchBrush CHS ~DIAGCROSS, 


RGB (0, 0, 255)) ; 
SelectObject (ps. hdc, npeuah) i. 


SetRect (&rRect, 30, 


0, 80, 90) ; 


if (RectVisible (ps. hdc, BrRects) 


Ellipse (ps. 


rRect.right, 


hdc, rRect. left, rRect. top, 
rRect.bottom) ; 


= EndPaint ChWnd, &ps) ; 
DeleteObject ChBrush) ; 
: DeleteObject ChRgn) ; 
: break ; 
[Other program lines] 
RGB eWin2.0 e&Win3.0 8 Win 3.1 
Purpose | Creates a 32-bit color value when given the three primary color elements. 
Syntax COLORREF RGB (BYTE cRed, BYTE cGreen, BYTE cBlue) ; 
Description Windows uses 32-bit values to specify colors when creating pens and brushes. The 82-bit values 


encode three primary’color contributions, the red, green, and blue Slementts that make up a 


color. If all of the elements are 
_zero, the color is black (no in- 
tensity). If all of the elements 
_are equal to 255, the maximum 
value for a color element, the 
color is white. Other combina- 
tions give colors which are de- 
termined by the mixing of the . 


meetoam 
EK Itt 


ue 


Figure 11-73. RGBO Frample. 


primary values. Windows achieves colors which are not on the system wabétte by dithering, the 
process of mixing pixels of different colors to achieve an area average color similar to the pure 
color specified. Systems with advanced displays (better than 16-color VGA) can use the palette 
functions to achieve other pure colors. The RGB() macro will always result in the dithered color 
being used. RGBQ) and the Get_Color() macros are defined in WINDOWS. H as 


tdefine RGB(r,g,b) CCDWORD) ((CBYTE Cr) | CCWORD) (g)<<8)) | (CCDHORD) (BYTE) (b))<<16))) 


Adefine GetRValue(rgh) 
ddefine GetG¥alue(rgb) 
#define, GetBValue(rgb) 


C(CBYTE) (rgb)) 


CCBYTE) (CC CWORD) (rgb)) >> 8)) 
CCBYTE) (C(rgb)>>16)) 


Uses Specifying a color of a pen or brush. 

Returns “COLORREF, the 32-bit (DWORD) color value. 

See Also . CreatePalette(), PALETTERGB(), PALETTEINDEX() 
Parameters | b< . 
cRed BYTE: The red component of the color, 0 to 255. 
cGreen BYTE: The green component of the color, 0 to 255. _ 
cBlue BYTE: The blue component of the color, 0 to 255. 
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Example This example uses a series of sixteen brushes to paint sixteen rectangles on the screen. They 
show a smooth gradation in gray scale from the left to the right when displayed on the screen. The 
reproduction in Figure 11-73 does not fully capture the gray tones. Intermediate colors are repre- 
sented by dithered patterns if the colors are not available on the system palette. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
t 


PAINTSTRUCT ps ; 

HBRUSH hBrush ; 

int i; 

switch CiMessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
for (i =0; 1 < 16; it+) 


{ 
hBrush = CreateSolidBrush ¢ 
RGB Ci * 16, i * 16, 1 * 16)) ; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, i * 30, 0, (i +1) * 30, 50) ; 
SelectObject (ps.hdc, GetStockObject (WHITE_BRUSH)) ; 
/ DeleteObject (hBrush) ; ; 
} 
EndPaint (hWnd, &ps) ;° 
break ; 
[Other program lines] 
RounDRECT wWin2.0 mWin3.0 wm Win3.1 
Purpose Draws a rectangle with rounded corners. 
Syntax BOOL RoundRect(HDC ADC, int X1, int Y/, int X2, int Y3, int 
X8, int ¥3); 
Description The rectangle is drawn with the selected pen and filled with 
the selected brush. 
Uses This shape can be used to draw custom buttons. 
Returns BOOL. TRUE if the shape was drawn, FALSE on error. 
See Also CreateRoundRectRgn() lL cevernereenmanesnnemmnees 
Parameters : Figure 11-74. RoundRect() 
hDC HDC: The device context handle. Example. 
x1 int: The logical X coordinate of the upper left corner of the bounding rectangle. 
YI int: The logical Y coordinate of the upper left corner of the bounding rectangle. 
X2 int: The logical XY coordinate of the lower right corner of the bounding rectangle. 
Y2 . « int: The logical Y coordinate of the lower right corner of the bounding rectangle. 
X3 Z . int: The logical width of the ellipse used to round the corners. 
¥3 int: The logical height of the ellipse used to round the corners. 


Example This example paints a rounded rectangle using a hatched brush and the default black pen, as 
, shown in Figure 11-74. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ ; 


~ PAINTSTRUCT ps ; 
HBRUSH hBrush ; | 
\ 
switch (iMessage) ' /* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
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hBrush = CreateHatchBrush (HS_CROSS, RGB (0, 0, 255)) 3) 
SelectObject (ps.hdc, hBrush) ; 

RoundRect (ps.hdc, 10, 10, 80, 60, 25, 20) ; 

EndPaint ChWnd, &ps) ; 

DeleteObject ChBrush) ; 


break ; 
[Other program lines] | 
SELECTCLIPRGN BWin2.0 mWind0 mWin3.1 
Purpose Uses a region to clip output to a device context. Beha aie 8, 
Syntax int SelectClipRgn(HDC ADC, HRGN hRgn); ‘generic [- [= 
Description Before this function can be used, a region must be created. The pectin 


region is then selected into the device context as the clipping 
boundary with SelectClipRgn(). All subsequent output to the 
device context is only painted if it falls within the clipping re- 
gion. 
Uses Clipping regions are frequently efficient ways to draw complex 
shapes. For example, consider the example in Figure 11-75. A 
, direct algorithm drawing all of the lines that make up the inner 
circle to the right length would be slow and difficult to code. 
Using a clipping region allows the area to be filled witha simple 


Do it! Quit 


, call to Rectangle(). Figure 11-75. SelectClip- 
Returns int, the type of region selected. This can be any of the region "9n() Example. 


. types in Table 11-23. 


The new region has overlapping borders. 


ERROR No new region was created. 
NULLREGION The new region is empty. 
SIMPLEREGION __ The new region does not have overlapping borders. 
Table 11-23. Region Types. 
See Also CreateEllipticRgn(), CreateRectRgn(), CombineRgn() 
Parameters : . 
hDC HDC: The device context handle. . . 
hRgn HRGN: The handle of the region to use as the clipping region. . a 
Example In this example, the same rectangle is drawn twice. The first time, there is no selected clipping 


region.'The rectangle is drawn with a NULL brush, so only the border is displayed. An elliptical 
clipping region is then set up with the same bounding rectangle dimensions. The second time the 
rectangle is drawn, a hatched brush is used. Only the portion of the rectangle within the elliptical 
clipping region is drawn. (See Figure 11-75.) 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) © 
ra 


PAINTSTRUCT ps ; 

HBRUSH hBrush, hOldBrush ; 

HRGN hRgn ; 

switch (iMessage) ; /* process windows messages a] 
{ . 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SelectObject (ps.hdc, GetStockObject-(NULL_BRUSH)) ; 
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: A, ; 
‘ rr 


SelectObject (ps.hdc, GetStockObject ie ; 
Rectangle (ps.hdce, 10, 10, 100 ¢ 1002-7 


aT 


hBrush = CreateHatchBrush CHS _DIAGCROSS, 
RGB (0, 0, 255)) ; 
 hOldBrush = SelectObject Gon hde, hBrush) ; 
‘hRgn = CreateElLlipticRgn (10, 0s 100, 1003 ; 

SelectClipRgn (ps.hdc, hRgn) ; 
Rectangle (ps. ehdc, 10, 10, 100, 100) ; 
SelectObject'(ps.hdc, holdBrush) ; 
DeleteObject (hBrush) ; 
EndPaint (hWnd, &ps) ; 
DeleteObject ChRgn) ae 


ae break ; 

[Other program lines] . 

SELECTOBJECT 7 mWin2.0 mWin30 mWin3l 

Purpose Selects an object into a device context. 

Syntax HANDLE SelectObject(HDC DC, HANDLE hObject); 

Description Before an object like a pen, font, brush, or region can be used in painting operations, it must be 
selected into the device context. If the same type of object was already selected, it is displaced by 

_ the new object selected. . 

Uses Selecting pens, fonts, brushes, and regions into a aie context. Bitmaps can be selected into 
memory device contexts only. Logical color palettes are selected using the SelectPalette() func- 
tion, not SelectObject(). Use DeleteObject() to delete every object created after it is no longer 
needed. Do not delete stock objects. Do not delete objects currently selected into a device con- 
text. 

Returns The handle of the object being replaced. This is convenient, as it is frequently desirable to delete 

the previous object once it is displaced from the device context. 

See Also DeleteObject(), CreatePen(), CreateSolidBrush(), cre eieehienent); Lenn 
CreateEllipticRgn(), CombineRgen(), CreateFont() 

Parameters 
HDC: The device context handle. 

hObject HANDLE: The handle of the brush, font, pen, or region to select into the device context. It can be 
the handle of a bitmap if ADC is the handle of a memory device context es Chapter 15, 
Bitmaps). 

Example The previous example under SelectClipRgn() shows SelectObject() initially being used to select 
two stock objects. They are used to paint a rectangle’s border. Later the function is used again to 
select a hatched brush, prior to painting a second rectangle which is clipped by an elliptical 
region. The previous brush handle is saved as hOldBrush, allowing the old brush to be selected 
again into the device context prior to deleting the custom brush. Objects that are selected intoa _ 
device context should not be deleted until they are displaced by another call to SelectObject(). 

SETBRusHORG mm Win2.0 om Win3.0 mg Win3t 

Purpose Changes the origin used by the device context to line up pattern brushes. 

Syntax DWORD SetBrushOrg(HDC ADC, int X, int Y); . : 

Description Windows maintains a logical origin in order to calculate how to align water and hatched 

a brushes, SetBrushOrg() allows you to change this value. Setting the origin only affects a brush if 
the origin is changed before the brush is created, or after a call to UnrealizeObject(). 

Uses _Used to keep patterns from merging into nearby objects, such as with neighboring bars on a bar 


chart. 
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- Returns DWORD, the brush origin. The low-order word contains the X [=F “genetic fe t= 


- position. The high-order word contains the Y position. 

See Also GetBrushOrg(), CreateHatchBrush(), CreatePatternBrush(), in HH 
UnrealizeObject() 

Parameters 

hDC HDC: The device context handle. 

a int: The new brushX origin. Its value must be between 0 and 7. 

Y int: The new brush Y origin. Its value must be between0and7. [First Brush h Origin = 0,0 

Example This example paints two rectangles with hatched brushes. (See {gecond Brush Origin = 3, 3 


Figure 11-76.) The first brush is created with 0,0 as the brush’ ' 
origin. The second with 3,3 as the brush origin. The result is Figure 11-76. GetBrushOrg() 

that the two patterns are offset by three pixels. This type of and SetBrushOrg() Example. 

offset can be desirable when it is important to show a separa- 

tion between two areas, such as bars on a black and white bar chart. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ | 20 - 


PAINTSTRUCT ps ; 

HBRUSH ' - hBrush ; 

char cBuf C128) ; ‘ ise 
DWORD dwBrushOrg ; , 

switch (iMessage) /* process windows messages */ 

{ 


case WM_PAINT: 

BeginPaint ChWnd, &ps) ; 
SetBrushOrg (ps.hdc, 0, 0) ; 

_ hBrush = CreateHatchBrush dts CROSS, RGB (0, 0, (255)) ; 
SelectObject (ps.hdc, hBrush) | =. 
Rectangle (ps.hdc, 0, 0, 40, 100) ; 
dwBrushOrg = GetBrushOrg (ps.hde) ; 
TextOut (ps.hdc, 0, 110, cBuf, aopeinte CcBuf, 

“First Brush Origin = 4d, %d", 
LOWORD (dwBrushorg), HIWORD- CdwBrutsshOrg))) ; 
SelectObject (ps.hdc, GetStockObject (WHITE_BRUSH)) ; 
DeleteObject (hBrush) ; 
SetBrushOrg (ps.hdc, 3, 3) ; 
hBrush = CreateHatchBrush cis —CROSS, RGB (0, 0, 255).) ; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 41, 0, 80, 100) . 
dwBrushOrg = GetBrushorg. (ps -hde) : 
TextOut (ps.hdc, 0,140, cBuf, wsprintf CcBuf, 
"Second Brush Origin = 4d, %d", 
LOWORD (dwBrushOrg), HIWORD (dwBrushorg))) ; 

EndPaint (hWnd, &ps) ; 
perererbi see ChBrush) ; 


, break ; 
[Other program lines] 
SETPIXEL | mw Win2.0 m@Win30 mWin3.1 
Purpose _ Changes to the color of a single point on the device context. 
Syntax §.. . DWORDSetPixel(HDC hDC, int.X, int ¥, DWORD crColor); 
Description — This function sets the color of one point on the device context. The color will be the closest color 
to that specified by crColor possible within the limitations of the device. 
Uses : Only used in specialized point-by-point drawing operations such as drawing fractal images. Nor- 
' -mally, this function is avoided because the time needed e filla region on the device is unaccept- 
a ably long. - 
- Returns — 4 DWORD, the 32-bit color value that actually was pane This valle will ad be equal to erColor 


ifthe device can saa the exact color. 
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See Also GetPixel() 

Parameters , 

hDG HDC: The device context handle. 

Xx int: The logical X coordinate of the point to change color. 

Y int: The logical Y coordinate of the point to change color. 

crColor DWORD: The 32-bit color value desired. Use the RGB macro to create a color value. 

Example - This example shows a shaded rectangle being painted, one pixel at a time. The starting pixel 


color is first retrieved using GetPixel(). This color is then incremented and used to set the new 
color of the pixel with SetPixel(). This method of drawing is unacceptably slow. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps; 

OWORD dwColor ; 

int nRed, nBlue, nGreen, i, . : 

switch (iMessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
for (i =0; 1< 10; i++) 
t 
por Cj =0; j < 256 ; jt) 


dwColor = GetPixel (ps. hdc, i iD; 
nRed = (GetRValue (dwColor) + j) % 256 : 
nBlue = (GetBValue (dwColor) + j) % 256; 
nGreen = (GetGValue (dwColor) + j) % 256 ; 
SetPixel (ps.hdc, j, i, 

RGB (nRed, nGreen, nBlue)) ; 


} 

paapeane ChWnd, &ps) ; 

break ; 
{Other program lines] 
SeTPoLyFiLLMopE | gs Win20 mWin380 mWin3t 
Purpose Changes the polygon filling mode of a device context. 
Syntax int SetPolyFillMode(HDC ADC, int nPolyFillMode); 
Description The polygon filling mode determines how areas of intersection within the polygon are painted. 

This is only a factor if the lines defining the polygon cross. , 

Uses Used with GetPolyFillMode() to determine and change the oe mode. 
Returns int, the previous filling mode. NULL on error. 
See Also GetPolyFillMode 0 
Parameters 
hDC HDC: The devide context handle. 


Ruger ore int: The desired polygon oe mode. This can be either of the modes i in Table 11-24. 


ALTERNATE ~ The GDI fills in areas as ares 182, sees 3&4, etc. 


WINDING ~The GDI fils in the total area defined by the outermost lines. This will normally fill the entire interior of the 
polygon, except in cases where more than one intersection of areas defined by the polygon’s lines occurs 
(see the example). 
Table 11-24. Polygon Filling Modes. 
Example See the example under GetPolyFillMode(). 
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SETREcCT| ee oe —mWin2.0 m@Win30 mWin3.1 
Purpose _ Enters all four values for a RECT data structure. a os 
Syntax void SetRect(LPRECT pRect, int X/, int Y/. int X2, int ¥2); oy eneric| > re 
Description 'the RECT data structure is defined in WINDOWS.H as follows: [FT SeerrU ET ar 


Dott! Quit 


typedef struct tagRECT — 
g. “Gt . 
int left; . ‘ 
int top; 
int right; 
int bottom; 


} RECT; ot . 
SetRect() allows all four elements of the structure to be set 
‘with one function call. . 
Returns No returned value (void). . Figure 11-77. SetRect{) 
‘ Example. 

Parameters - 2 
lpRect LPRECT: A pointer to a RECT data structure. 
XI int: The.X coordinate of the upper left corner of the rectangle. 
Yl int: The Y coordinate of the upper left corner of the rectangle: 
X2 int: The X coordinate of the lower right corner of the rectangle. 
Y2 int: The Y coordinate of the lower right corner of the rectangle. 
Example In this example, SetRect() is used to fill in the values for a rectangle that is then used to define 


the bounding rectangle of an elliptical region. (See Figure 11-77.) 
long ‘FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


\ 
PAINTSTRUCT _PS 7 
HBRUSH hBrush ; 
HRGN hRgn ; / 
RECT _ Rect ; , 
switch (iMessage) , /* process windows messages */ 
{ 


case WM_PAINT: ‘ 
BeginPaint ChWnd, &ps) ; 
hBrush = CreateHatchBrush (CHS_DIAGCROS 

RGB (0, 0, 255)) ; 

SetRect (&rRect, 10, 10, 100, 80) ; 
hRgon = CreateElLlipticRgnIndirect (&rRect) ; 
FILLRgn (ps.hdce, hRgn, hBrush) ; 

Bo EndPaint (hWnd, &ps) ; 


DeleteObject ChBrush) ; : 
DeleteObject (hRgn) ; 
break ; ; 
[Other program lines] . 
SETRECTEMPTY | | mWin2.0 mWin30 mWin3l 
Purpose Sets all the elements of a RECT data structure to zero. 
Syntax void SetRectEmpty(LPRECT lpRect); | 
Description This is a shortcut method to zero all of the values in a RECT data structure. See SetRect() for the 
definition of RECT. es 
Returns No returned value (void). . 
See Also IsRectEmpty(), SetRect() 
Parameters = : : 
lpRect LPRECT: A pointer to a RECT data structure. _ 
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In this case, a rectangle is defined when the program starts (WM_CREATE message received). 
The rectangle is used to define a clipping region, which is used to paint an ellipse on the client 
area. When the user clicks the “Do It!” menu item, the rectangle is set to empty. The next 
WM_PAINT message clears the client area. 


tong FAR PASCAL WndProc CHWND hWnd, a SNestace, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps; / 

HBRUSH hBrush ; 

HRGN hRgn ; 

static RECT rRect ; 

switch CiMessage) /* process windows messages */ 
{ 


case UM_CREATE: 
SetRect (&rRect, 10, 10, 80, 120) ; 
break ; 
case WA_PAINT: 
BeginPaint ChWnd, Eps) ; 
if CiisRectEmpty (&rRect)) 


{ 

hBrush = CreateHatchBrush CHS_DIAGCROSS, 
RGB (0, 0, 255)) ; 

hRan = CreateELlipticRgnindirect (&rRect) ; 
FILLRgn Cps.hdc, hRgn, hBrush) ; 
SelectObject (ps.hdc, GetStockObject CWHITE_BRUSH)) ; 
DeleteObject ChBrush) ; 
DeleteObject ChRgn) ; 

} 

EndPaint Chuind, &ps> ; 

break ; 

case WA_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_OOIT: /* User hit the “Do it" menu item */ 
SetRectEmpty (&rRect) ; 
Inystidetekect Chuind, AULL, TRUE) ; 


break ; 
[Other program lines] 
. SeTRectReN mWin2.0 gWin3.0 mWin3.1 
; Parpose Changes the bounds of a rectangular region. 
Syntax void SetRectRgn(HRGN hRgn, int X7, int Y/, int X2, int ¥2); 
Description This is an efficient way to change the size of a rectangular re- 
gion. The region must already exist, with memory allocated in 
the local heap by a previous call to CreateRectRgn(). 
Uses Handy, when there is a series of rectangular regions used in 
sequence. See the following example. The application must 
delete the region before the program exits to return all memory 
to the system. 
Returns No returned value (void). 
See Also CreateRectRen() = 
Parameters Fane 11-78. “SetRectRgnt ) 
hRgn HRGN: Ahandle to the rectangular ‘hoe toresize.The region 4xample. 
must have been allocated by a previous call to CreateRectRgn(). 
Xl int: The logical X coordinate of the upper left corner of the rectangle. 
YI int: The logical Y coordinate of the upper left corner of the rectangle. ™ 
Xx? int; The logical X coordinate of the lower right corner of the rectangle. 
¥2 "int: The logical ¥ coordinate of the lower right corner of the rectangle. 
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Example This example efficiently draws a series of progressively smaller regions. The same region is re- 
used (not destroyed and then created) each time. SetRectRgn() establishes the region’s size 
before each painting. (See Figure 11-78.) Note that memory for the region is allocated when the 
program starts (WM_CREATE message received). The region is destroyed as the program exits, 
freeing the memory associated with the region. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : 


PAINTSTRUCT ps ; 

HBRUSH hBrush ; 

static HRGN hRgn ; 

int i; 

RECT rRect ; 

switch CiMessage) /* process Windows messages */ 

a 

case WH_CREATE: 

hRgn = CreateRectRgn (0, 1, 2, 3) ; /* arbitrary size */ 
break ; 


case WM_PAINT: 
: BeginPaint (hWnd, &ps) ; 
SetRect (&rRect, 10, 10, 100, 100) ; 
’ for (4 =03;1<8; i++) 
{ 


SelectObject (ps.hdc, 
GetStockObject (BLACK_BRUSH)) ; 
SetRectRgn ChRgn,rRect.left, rRect.top, 
rRect.right, rRect.bottom) ; 
PaintRgn (ps.hdc, hRgn) ; 
InflateRect (&rRect, -5, -5) ; 
SelectObject (ps.hdc, 
GetStockObject (WHITE_BRUSH)) ; 
SetRectRgn ChRan,rRect. left, rRect.top, 
rRect.right, rRect.bottom) ; 
PaintRgn (ps.hdc, hRgn) ; 
InflateRect (&rRect, -5, -5) ; 


} 
EndPaint ChWnd, &ps) ; 
break ; 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
InvalidateRect (hWnd, NULL, TRUE) ; 
break ; : : 

case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
‘break ; 

} 

break ; 

case WM_DESTROY: /* stop application */ 
DeleteObject ChRgn) ; 
PostQuitMessage (0) ; 


break ; 
' default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; . 
} 
return (OL) ; 
} 
SETROP2 Win2.0 mWin30 wm Win31 
Purpose Changes the raster drawing mode of a device context. 
Syntax int SetROP2(HDC ADC, int nDrawMode); 
Description The default, R2_COPYPEN, paints the pen color regardless of the underlying colors. With the 


other drawing modes, the pen is drawn on the device context after comparing the pen color to 
the existing color at eachX, Y position being drawn. With color devices, each of the three primary 
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Uses 


Returns 


See Also 


Parameters 
hDC . 


nDrawMode 


f 

colors is dealt with separately, using the 
same binary logic. The blue element of the 
pen color is compared to the blue element 
of the pixel, etc. 

Only a few of the ROP2 operations typi- 
cally are used. The common ones are 
R2_NOT, which makes the pen always vis- 
ible and R2_XORPEN which makes the 
pen line disappear if the same line is 
drawn twice. 
int, the previous drawing mode. This is 
one of the 16 values shown in Table 11-25. 


GetROP2 


HDC: The device context handle. 
int: One of the following drawing modes. 
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WHITE 

NOP 

NOT 
COPYPEN 
NOTCOPYPEN 


MERGEPENNOT 
MASKPENNOT 
MERGENOTPEN 
MASKNOTPEN 
MERGEPEN ‘ 
NOTMERGEPEN 
MASKPEN 
NOTMASKPEN 
XORPEN 


_NOTXORPEN 


In the Boolean operation column, the “P” Figure 11-79. SetROP2() Example. 

stands for the pen color value and the “D” 
stands for the display color value. For simplicity, the explanations are in terms of a black and 
white display. For color displays, the same logic is applied to each color element (red; blue, 


green). 
2 “oes: Boolian Operation... Comments’ = 
R2_BLACK 0 Always black. 
R2_WHITE 1 Always white 
R2_NOP D No effect on display. 
R2_NOT ~D Invert display under line. 
R2_COPYPEN ~#P Pen color painted regardless of display. 
R2_NOTCOPYPEN ~P Pen color inverted regardless of display. 
R2_MERGEPENNOT P|~D 
-R2_MASKPENNOT P&~D_ 
R2_MERGENOTPEN ~PID 
R2_MASKNOTPEN ~P&D 
R2_MERGEPEN PID 
R2_NOTMERGEPEN ~(P!D) 
_ R2_MASKPEN P&D 
R2_NOTMASKPEN ~(P &D) 
R2_XORPEN PAD A black pen inverts the device pixels. Drawing twice at the 
same location erases the line. 
R2_NOTXORPEN (PAD) 


Table 11-25. Raster Drawing Modes. 


Example This example (see Figure 11-79) demonstrates all 16 ROP modes by painting a black and white 
line against black and white backgrounds with each of the ROP2 modes. (Credit should be given 
to Peter Norton and Paul Yau for this clever way of displaying the drawing modes.) 
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long FAR PASCAL WindProc CHWND hWnd, unsigned ee ae WORD wParam, LONG lParam) 
r 4 . sn = ; ‘. 


PAINTSTRUCT ps; 

HPEN hPenWhite, hPenBlack ; 

int i; ; 
int nROPModes C16] = {R2_BLACK, R2_WHITE, R2_HOP, 


R2_NOT, R2_COPYPEN, R2_NOTCOPYPEN, R2_MERGEPENNOT, 
R2_| MASKPENNOT, R2 _MERGENOTPEN, R2_MASKNOTPEN, R2_MERGEPEN, 
R2_NOTMERGEPEN, R2_MASKPEN, R2_NOTMASKPEN, R2_XORPEN, 
R2_NOTXORFEN} ; 
char *cROPModeNames [£16] = {"R2_BLACK", "R2 WHITE", 
"R2_NOP", “R2_NOT", "R2_COPYPEN", “R2_NOTCOPYPEN", 
“R2_MERGEPENNOT", “R2_MASKPENNOT", “R2_MERGENOTPEN", 
“R2_MASKNOTPEN", “R2_MERGEPEN", "R2_NOTMERGEPEN", 
“R2_MASKPEN", “R2_ NOTMASKPEN", "“R2_XORPEN", 
“R2_NOTXORPEN'? ; 


‘switch CiMessage) /* process windows messages w/ 
{ 


case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
hs f TextOut (ps.hdc, ‘0, 0, “BLACK PEN", 9) >; 

ae TextOut (ps.hde, 80, 0,. “WHITE PEN", 9); 
SelectObject (ps hdc, GetStockObject (BLACK_BRUSH) > 
Rectangle (ps.hdc, Q, 20, 40, 270) ; 
SelectObject (ps.hdc, GetStockObject CWHITE_| BRUSH) ) 
Rectangle (ps.hdc, 40, 20, 80, 270) ; 
SelectObject (ps.hdc, GetStockObject BLACK BRUSH) ) 
‘Rectangle (ps.hdc, 80, 20, 120, 270) ; 
SelectObject (ps.hdc, GetStockObject WHITE. BRUSH)) ; 
Rectanyle (ps.hdc, 120, 20, 160, 270) ; 
hPenWhite = CreatePen (ps_SOLID, 3, 

RGB (255, 255, 255)) ; 


we @e 


me 


Va | hPenBlack = CreatePen (PS_SOLID, 3, OL) ; 
for (1=0; 1<16 3; i++) 
{ 


SetROP2 (ps.hdc, nROPModes [Ci]) ; 
SelectObject (ps.hdc, hPenBlack) ; 
MoveTo (ps.hdc, 0, (i * 15) + 27) ; 
LineTo (ps.hdc, 77, (i * 15) + 27) ; 
SelectObject (ps.hdc, hPenWhite) ; 
MoveTo (ps.hdc, 80, (i * 15) + 27) ; 
LineTo (ps.hdc, 157, (4 * 15) + 27) ; 
oe ™~ - TextOut (ps.hdce, 165, (i * 15) + 20, 
cROPModeNames C41, 
strlen (cROPModeNames C1]3)) ; 
} 
EndPaint ChWnd, &ps) ; 
DeleteObject ChPenBlack) ; 
Deletedbject ChPenWhite) 3 
break ; 


[Other program lines] 


SetSysCoiors. mWin2.0 mWin30 mWin3l 

Purpose Changes the color values that Windows uses to paint pacer and nonclient areas of the 
screen and windows. . 

Syntax void SetSysColors(int nChanges, LPINT [pSysColor, DWORD FAR */pColorValues); 


Description Windows maintains a table of 20-color values that are used to specify what color to paint the 
borders, buttons, etc. This function allows you to change those values temporarily. The changes 
remain in effect for the duration of the Windows session. The changes are not permanent, as the 


._ WIN.INI file is not modified. 23 . 
-Uses - — -_~_‘ Temporary changes to the system colors. 7 
Returns. No returned value (void). . 


See Also _ GetSysColor() 


Parameters 
nChanges 
lpSysColor 
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int: The number of system color values that will be changed. 
LPINT: A pointer to an array of at least nChanges integers. The value in each array element 


determines which color will be changed. This value can be any of the colors listed in Table 11-26. 


COLOR "ACTIVEBORDER 
COLOR_ACTIVECAPTION 
COLOR_APPWORKSPACE 
COLOR_BACKGROUND 
COLOR_BTNFACE 
COLOR_BTNSHADOW 
COLOR_BINTEXT 
COLOR_CAPTIONTEXT 
COLOR_GRAYTEXT 


COLOR_HIGHLIGHT 
COLOR_HIGHLIGHTEXT 
COLOR_INACTIVEBORDER 
COLOR_INACTIVECAPTION 
COLOR_MENU 
COLOR_MENUTEXT | 
COLOR_SCROLLBAR 
COLOR_WINDOW 
COLOR_WINDOWFRAME 
COLOR_WINDOWTEXT 


- . Table 11-26. System Colors. 
DWORD FAR *: A pointer to an array of DWORD values that contain the 32-bit color values to use 


‘IpColorValues 


The active dui border 


The active window caption. 

The background color for MD! (multiple document interface) applications. 
The desktop (background on which all programs and icons are painted). 
Button face color. 

Button edge color. 

Button text color. 

The caption text color. 


Grayed (disabled) menu item text color. The returned color is set to zero if the display does not 
support a solid gray color. 


Selected item color in a control. 
Text color in a selected control. 
Color of an inactive window border. 
Color of an inactive window caption. 
The menu background color. 

The menu text color. 

The scroll bar gray area. 

The window background color. 

The window frame color. 

The color of text in a window. 


for each color specified by the lpSysColor elements. There must be at least nChanges elements 
in the array. ! 

Related Messages WM_SYSCOLORCHANGE should be sent after the function is called. This message notifies all 
applications that the system colors have been modified. 


When the user clicks the “Do It!” menu item, the system color for the active caption is changed to 
bright red, and the system color for button text is changed to blue. Windows automatically re- 
. paints the nonclient areas of the windows to accommodate these changes. The changes remain in 
effect until the Windows session is ended. No change is made to the WIN.INI file settings, so the 
changes do not appear the next time Windows is.started. 


oe FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


. Example 


int nColorIndex C2] ; 
DWORD enColorValue [2] ; 


switch CiMessage) /* process windows messages */ 
€ 


case WM_COMMAND: 


je process" menu items */ 
switch (wParam) ; 
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case IDM_DOIT: 
nColorIndex CO] 
nColorValue [0] 
nColorIndex £1] 
nColorValue C1] 


RGB (255, 0, 0; 
COLOR _BINTEXT ; 


Hou aoa 


RGB (0, 0, 255), : 


/* User hit the “Do it" menu item */ 
COLOR PCTAMECAP TION 2 


SetSysColors (2, nColorindex, nColorVatue) 2 
PostMessage (-1, WM_SYSCOLORCHANGE, 0, OL) ; 


break ; - 

[Other program lines] 
UnionREcCT wWin2.0 mWin30 mWin3l 
Purpose Sets the size of a rectangle equal to the smallest rectangle that will enclose two other rectangles. 
Syntax int UnionRect(LPRECT /pDestRect, LPRECT lpSrclRect, Trae E 

LPRECT IpSrc2Rect); — generic [~-[*- 
Description The union of two rectangles is a third rectangle that encloses Do 0 Quit " 

the other two. The source rectangles can be either separate or = SS 

overlapping er a 
Uses The union is the smallest area that can be painted to cover the 

two source rectangles. ei sdedbesheonbeabad 

‘SRO BREE 
Returns int. Zero if the union is empty, nonzero if the union is not an tt tt tt 
. empty rectangle. 

See Also Rectangle(), IntersectRect(), IsRectEmpty() a 
Parameters 2, _ Figure 11-80. UnionRect{) 
lpDestRect LPRECT: A pointer to a RECT data structure that willholdthe Example. 

union rectangle, . 
lpSrc1Rect LPRECT: A pointer to a RECT data structure containing the first source rectangle. 
lpSrc2Rect LPRECT: A pointer to a RECT data structure containing the second source rectangle. 
Example This example creates two rectangles of fixed size, and then creates a third which is the union of 


the first two. The union is shown as the hatched area, the smallest rectangle that encloses both of 


the other two. (See Figure 11-80.) 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


PAINTSTRUCT ps ; 

RECT r1, r2, 73 ; 
HBRUSH hBrush ; 
HPEN hPen ; 


t 
switch (CiMessage) 


[Other program lines] 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SetRect (&r1, 10, 10, 100, 100) >; 
SetRect (&r2, 50, 50, 140, dat is 
UnionRect (&r3, &rt, &r2) > 
hBrush = 
SelectObject (ps.hdc, hBrush) ; 


/* process windows messages */ 


CreateHatchBrush “HS CROSS, RGB (0, G, 255)) ; 


Rectangle (ps.hdc, r3.left, r3.top, r3.right, r3.bottom) ; 
SelectObject (ps.hdc, GetStockObject (NULL_BRUSH)) ; 


DeleteOQbject (hBrush) ; 


hPen = CreatePen (PS_SOLID, 3, RGB (255, 0, O)) ; 


SelectObject (ps.hdc, hPen) ; 


Rectangle (ps.hdc, ri1.left, re top, ri.right, “rt. bottom) 
Rectangle (ps.hdc, r2.left, r2.top, re. right, r2.bottom) 


EndPaint ChWnd, &ps) ; 
DeleteObject (hPen) 7 
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UNREALIZEOBJECT Win2.0 wWin3.0 mWin3.1 
Purpose Used to reset a brush origin or a palette. 

Syntax BOOL UnrealizeObject(HBRUSH hObject); 

Description This function resets a device context so that it does not “realize” the brush origin or palette, 


which allows a new brush origin or palette to be selected into the device context. Do not attempt 
to reset the origin of a stock brush. 


Uses Used to make sure rectangles filled with hatched brush pat- 

terns do not “run into” each other. 

Returns BOOL. TRUE if the function unrealized the object, FALSE on 
error. 

See Also SetBrushOrg() 

Parameters 

hObject HBRUSH: A handle to a brush or a logical palette. If hObject is 
a brusn handle, it cannot be currently selected into a display 
context. 

Related Messages WM CTLCOLOR rt 

Example This example shows two cases where rectangles are drawn with 


a hatched brush pattern. In the uppercase, both are drawn Figure 11-81. Unrealize- 
with the same brush and the patterns align. In the lowercase, Object() Example. 
the same brush is used, but the origin of the brush is reset be- 

fore painting. Resetting the origin allows the brush origin to be moved, resulting in mismatched 
patterns. Note that it is necessary to remove the brush from the device context to change the 
brush origin. Selecting a stock object does this without creating additional memory demands. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 

RECT ri, r2; 

HBRUSH hBrush ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_PAINT: 

BeginPaint (hWnd, &ps) ; 
SetRect (&r1, 10, 10, 50, 50) 
SetRect (&r2, 50, 10, 90, 50) 
hBrush = CreateHatchBrush CHS_CROSS, RGB (0, 0, 255)) ; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, ri.left, ri.top, rt.right, r1.bottom) ; 
Rectangle (ps.hdc, PeRLehts r2.top, r2.right, r2.bottom) ; 
OffsetRect (&r1, 0, 60) ; 

-OffsetRect (&r2, 0, 60) ; 
SelectObject (ps. hdc, Ecectuckoniect (WHITE _BRUSH)) ; 
UnrealizeObject (hBrush) ; i 8 
SetBrushOrg (ps.hdc, 0, 0) ; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, ri.left, r1.top, ri.right, ri.bottom) ; 
SelectObject (ps.hdc, GetStockObject CWHITE_BRUSH)) ; 
UnrealizeObject (hBrush) ; 
SetBrushOrg (ps.hdc, 5, 3) ; 
SelectObject (ps.hdc, ferushy3 

- Rectangle (ps.hdc, r2.left, 2 top, r2.right, 2. bottom) ; 
EndPaint (hWnd, &ps) i 
DeleteObject ShBedene 
break ; 


Sa Ne 


[Other program lines] 
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UppaTEWINDOW mWin2.0 w8Wind0 mWin3l 
Purpose Forces an immediate WM_PAINT message, which updates the window. 
Syntax void UpdateWindow(HWND hWnd); 
Description : The WM_PAINT message is sent directly to the window's message processing function, bypassing 
the message queue. This allows a program to repaint the client area before other messages 
- (mouse movements, etc.) are processed. WM_PAINT is sent only if there is an update region for 
the window that requires repainting. Use InvalidateRect() to create an update region if none 
exists. To put a WM_ PAINT message on the application’s message queue, simply call Invali 
dateRect(). 
Uses Rapid repainting of a window after some change to the client area was made. 
Returns No returned value (void). 
See Also InvalidateRectQ), InvalidateRgn(), BeginPaint(), EndPaintQ 
Parameters ; 
— hWnd HWND: The HANDLE to the window needing repainting. 
Related Messages WM_PAINT 
Example In this example, ten lines of text are written to the ‘ines area, To erase them, the client area is 


invalidated, and UpdateWindow() called. This repaints the client area background, erasing the 
text. 


long re en WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ‘ é is 


Dc hoc ; 
RECT rClient ; 
int i; 
switch CiMessage) /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
: case IDM_DOIT: /* user hit the “Do it" menu item */ 
hDC = GetDC (hWnd) ; 
for (i =Q0; i1<10; i++) 
{ 
! TextOut (hDC, 10, 10 + (1*15), 
“This text will be erased.", 25) ; 

} : 
ReleaseDC ChWnd, HDC) ; 
GetClientRect ChWnd, &rClient) ; 
InvalidateRect Chund, eceiients. TRUE) ; 
Unda tel indow ChWnd) ; 
break ; 

[Other program lines] 

VALIDATERECT os ~ | BWin2.0 mWin3.0 mWin31 

Purpose Removes a rectangular area from the window’s update region. This is done to avoid having 

WM_PAINT messages generated to repaint invalid parts of the client area. 
Syntax |. ,; void ValidateRect(HWND hWnd, LPRECT lpRect); _ m 
Description Windows keeps track of parts of a window’s client area that have become invalid due to scrolling, 


resizing, or uncovering parts of the client area from beneath other windows. These areas are 


called “invalid.” Windows will send a WM_PAINT message to a window that contains invalid ré- | ~ 


gions to allow repainting. To temporarily avoid repainting, an application can validate regions. 
Use GetUpdateRect() to determine the size of the invalid rectangle, and use ValidateRect() to 
validate it. Once validated, the region will not cause WM_PAINT messages. 
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Uses ; 


Returns 
See Also 


Parameters 
hWnd 


IpRect - 
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/ . 
Most often used with windows that scroll the client area. It may be more efficient to repaint the 


_ area uncovered by scrolling in the part of the program that scrolls the window, rather than pass- 


ing the,job to the WM_PAINT handling logic. In processing WM_PAINT messages, the update 
rectatigle i is part of the PAINTSTRUCT data structure filled by BeginPaint() at the start of the 
WM_PAINT logic. 


No returned value (void). 
GetUpdateRect(), BeginPaint() 


As. 


HWND: The window handle. 

LPRECT: A pointer toa RECT data structure that contains the eadee to validate on the client 
area. Use GetUpdateRect() to retrieve this value. If the value is within the WM_PAINT processing 
logic, the update rectangle is part of the PAINTSTRUCT data filled by BeginPaint(). 


cpre ye WM_PAINT 


Example 


VALIDATERGN 


Description 


Returns 
See Also 
Parameters 
hWnd 

hRgn 


See the example under the ‘GetUpdateRect() function description. 


gWin20 m@8Wind.0 m&Wind.l 
Removes a region from the window's update region. This is done to avoid having WM_PAINT 
messages generated to repaint invalid parts of the client area. 
void ValidateRgn(HWND hWnd, HRGN hRgn); 
This is similar to ValidateRect(), except the area to be validated is passed as a region instead of 
arectangle. Windows keeps track of parts of a window’s client area that have become invalid due _ 
to scrolling, resizing, or uncovering parts of the client area from beneath other windows. These 


"areas are called “invalid.” Windows will send a WM_PAINT message to a window that contains 


invalid regions to allow repainting. To temporarily.avoid repainting, an application can validate 
regions, Use GetUpdateRgn() to determine the size of the invalid rectangle, and use Validate 
Rgn() to validate it. Once validated, the region will not prompt WM_PAINT messages. 


Most often used with windows that scroll the client area. It may be more efficient to repaint the 
area uncovered by scrolling in the part of the program that scrolls the window, rather than pass- 
ing the job to the WM_PAINT handling logic. 


No returned value (void). 


GetUpdateRgn(Q), ValidateRect(), Retiptetenek) 


_HWND: The window handle. 


HRGN: The handle of the region containing the update area to validate. 


Related Messages WM_PAINT 


Example 


See the example under the GetUpdateRgn() function description. 
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In the last chapter, the standard Windows RGB color model was used to create colored brushes and pens. Except for 
20 pure tones (less on some systems), most colors that are displayed using objects created from RGB colors are 
. painted with a “dithered” brush. This technique mixes the different colored pixels that average to the desired color. 
With the versions of Windows prior to 3.0, the RGB color model was the only tool available. Windows 3.0 has the added 
ability to work with color displays and other devices which can display more than 16 colors at one time. The IBM 8514/A 
and Super VGA video boards are becoming increasingly common, and many displays are now able to show 256 colors 
from a selection of many million. Windows uses color palettes to control these powerful display systems. 


Hardware Palettes 


Only high-cost video systems are able to simultaneously display every possible color at every location on the screen. 
_ Most video boards display a limited number of colors. The EGA standard was limited to eight simultaneous colors; VGA 
started with 16; and Super VGA and IBM 8514/A boards show between 64 and 256 colors at once. About a megabyte of » 
video memcry is needed to support 256 colors on a VGA or Super VGA resolution screen. With the limited number of 
colors that can be shown at one time, video boards must keep track of which colors to use. Using a Super VGA board as 
an example, the 256 colors that can be shown at one time are selected from a range of 256 * 256 * 256 = 16,777,216 
possibilities. That range of colors is determined by thie video board’s use of three bytes of information to specify the 
red, green, and blue elements of a color. ; . 

To show a color on the screen, the video board first sets the RGB (Red, Green, Blue) values for all of the colors 
that can be shown at one time. These settings are called the “hardware color palette.” When a pixel is to be displayed, 
_the color of the pixel is set to the RGB value of one of the hardware color palette values. Changing the color of a pixel 
only requires that a different hardware palette entry be referenced. If the RGB value of a palette entry is changed, 
then every pixel displaying that palette color will be immediately changed on the screen. Figure 12-1 shows the 
mapping of the hardware palette to the screen. 

Hardware palettes are used on video systems for speed and memory conservation. The ablility to specify every 
pixel’s RGB value individually would take about three megabytes of memory. Limiting the choices to 256 colors in the 
palette at one time cuts the memory needed down to one megabyte. In addition, the color of a pixel can be changed by 
just specifying one byte of information, the new palette entry number. This is faster than specifying three bytes for the 
RGB value of each pixel. Speed is a big issue on video equipment, especially with the video resolution expanding to the 
1,024 wide by 768 high pixel resolution and beyond. 


Color Palettes in Windows 


Windows runs into problems when trying to support 
hardware color palettes. If Windows were to allow any 
program to change the RGB color settings in the video 
display hardware palette, every application running on 
the system would be affected. For example, if the hard- 
ware palette color for black were changed to blue, then 
every black pixel in every visible window would instantly 
change to blue. This violates the basic principle that Figure 12-1. A 256-Color Super VGA Hardware Palette. 


Hardware Palette ’ Video met 
Red Green Blue Individual Pixels 


128 
) 128 0 

) ) 128 
128 128 O... 


ALL. 256 Values 
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Windows applications run as separate windows that do not interfer with each other. Another problem is that Windows 
programs can run on any system, many of which will not display as many colors as a Super VGA system. 

Windows gets around these problems with two concepts: the “system default palette” and the “logical palette.” 
They are both ways to deal with the actual display equipment’s “hardware palette.” The system default palette is a 
group of 20 reserved colors that Windows uses to paint menus, buttons, the screen desktop background, and dithered 
brushes. If the display equipment supports less than 20 simultaneous colors, some of the 20 entries will be the same. 
This is normally not a problem, as the text color inside a button can be the same as the text color for menu items, etc. 
Normally, application programs will not change the system colors. If you have a burning desire to change the system 
default palette, there are support functions, such as SetSysColors(). With modern display adapters there are usually 
plenty of extra color choices to use without modifying the system default palette. 


The Logical Palette 


The logical palette (See Figure 12-2) is a memory area that mimics the hardware palette in the video board. Each 
entry in the logical palette contains an RGB value that Windows applications can Use for creating colored pens, fonts, 
brushes, and bitmaps. The logical palette can contain more entries than the hardware device actually supports. In 
this case, the “extra” logical pal- 
ette entries are mapped to the LogicalPalette Hardware Palette miceoDepty 
closest hardware palette color. If Red Individual Pixels 
the logical palette contains 
fewer entries than the hardware 
palette, some of the hardware 
colors are not used. © 

The logical palette gets 
around the problem of how to. 
deal with systems with small [77777 777777777 
hardware palettes. This still . 
leaves the issue of different ap- Figure 12-2. The Logical Palette. . 
plications running at the same 
time, demanding different colors. There is no escaping the fact that Windows runs on real hardware with only one 
video card and only one hardware palette. If two different applications are running at the same time and both want to 
use extended color palettes, the programs will interfere with each other. 

Windows minimizes the damage caused when several programs use the logical palette by giving the active window 
priority in specifying colors for the logical palette. Inactive windows make due with whatever colors are left. Inactive 
windows use any remaining unused entries in the logical palette, and then use the closest matching colors for any 
remaining requests on the palette. This is not as much of a problem as it might seem because most programs use only 
the system colors, which are normally reserved. Windows will allow you to play dangerously, by letting the logical 
palette change the system palette. The SetSystemPaletteUse() function is provided for this purpose. 


Green Blue Red Green Blue 


128 
0 128 #0 

0 0 128 
128 128 O... 


ALL 256 Values 


Creating a Logical Palette 

Activatirtg a logical palette is a three step process. 

1. The color settings for every entry in the palette that the application will use are written to an array, and then 
turned into a palette using the CreatePalette() function. CreatePalette() returns a handle to the palette, which 
is normally stored as a static variable for use later in the program. 

2. The palette is selected into the device context using SelectPalette(), which is similar to the SelectObject() func- 
tion described in the last chapter for selecting pens, brushes, and fonts. The difference is that selecting a palette 
does not immediately change the colors because the video hardware paiette entries are not changed until the 
palette is “realized.” © 

3. The palette is “realized” using RealizePalette(), which writes the logical palette settings to the hardware palette, 
changing the color settings in use. As mentioned previously, the active window is given priority for the hardware 
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+ color. settings. Any leftover hardware palette entries can be used by inactive windows, pane ents bevont the’ 
limits of the video hardware are mapped to. the closest color available. - rye Te ati Bay NE eas 


In processing WM: PAINT messages, it is Tiecessary to: sélect'and realize ihe: 3 ligieal palette every’ reir éhe mes- 
sage is processed. ‘Wheri the program exits, the logical paletté is freed from memory with DéleteObject(). The logical: 
palette’ can’ be ‘résizéd: and‘ have entries ‘changed without making‘ a new palette by using the ResizePalette() and: 
SetPaletteEntries(): functions. You can use rapid changes i in the palette colors to créate the illusion that an object is 
moving onthe screen byi using AnimatePalette(). To use palette’entries for animation, a number of he) he ideical palette 
entries will need to be the same color, but used to pained unteren nae of the screen. ya, 


Windows Color Palette Messdges: 


Because of the interactions between active and inactive windows using color nisletas, communication between appli- . 
cations is needed. Windows gends a WM_QUERYNEWPALETTE message to an application that realizes a logical pal- 
ette when ‘it is about to get theiriptit focus: This message offers: the chance to again realize the pales regaining: 
colors that may have been'lost to other applications while the window was inactive: . 
‘ The WM_PALETTECHANGED message is sent to all windows when any application realizes its 3 logical palette. For- 
inactive windows, this is notification that colors may be lost to the window with the input focus. The UpdateColors() 
function is provided to efficiently:respond to the new palette choices. The example in this'chapter with 
. UpdateColors () shows normal processing logic for handling WM_PALETTECHANGED and WM _QUERYNEWPALETTE 
messages. Windows sends a WM_ ~SYSCOLORCHANGE message to all windows if an application changes the system 
palette. The best approach. for an application rocevine ‘this message is to delete any static brushes: and pens and’ 
redraw them using the new system colors. ee 
- ‘Caution: The array used in CreatePalette() to define all lof the colors'for the logical plete can exceed ie stack 
spice if it is stored as a local variable. It is best to allocate memory for the array. ~~ os 
The colors displayed with the palette functions do not match those produced by the dithering process used byt the 
RGB color model. In general, the palette enjries are much darker. Simply. converting an applica on tat used RGB 
colors to comparable palette colors may not result in an acceptable image. 
Check the capabilities of the physical hardware beforé using the palette functions. The GetDeviceCatis() fiction 
provides considerable information about what the hardware device can and cannot-do: In particular, check the: 
RASTERCAPS iridex valite- RC. PALETTE to see if palette chaiges a are € supported. The NUMCOLORS index allows the 
number of colors that cai simultanéoiisly be displayed: aes on ie ; 


Palette Function Summary 0600 eee ae 
Table 12- 1 summarizes the Windows functions that provide support for color palettes. ee 


AnimatePalette ey , “ ./ Rapidly.changes the color.of objects painted with colors from a logical palette::::: 0... -.:t%as 


CreatePalette , Creates a logical palette. : sd , Fo oitg 
GetPaletteEntries Determines the color values for a range of entries in a logical pate, : . 7 ; 
GetNearestPaletteIndex Finds the palette entry, number that most closely matches a given 1 PGB v value, 
‘GetSystemPaletteEntries.. sf - Determines the colors of each of the system palette items. a % fener ise 
einai Determines if an application can change the ee palette). 

-PALETT| EINDEX » os — esa logical palette. color directly... 4 ion og IP SOE BE 
‘PALETTERGB *: aE “Retrieves the color which i is closest to the desired RGB color: from ‘the logical palette = : 
‘abate nes "Maps the logical palette selected into a device context ‘to ‘the hardware palette. eae A 
ResizePalette . fe stony... Changes the size of a logical palette. 

‘SelectPalette : - - a s “a - _ Selects. a color palette into. a device context. 
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SetPaletteEntries, ~ Changes the color values in alogical-palette” - . 0 ib acer rend via aes a 

SetSysColors Changes the system colors used to paint window objects. 

SetSystemPaletteUse Allows modifications to the system color palette. 9° . sane 
pdateColors 


Redraws the client area when the application does not have the input focus, but has realized a 
logical palette. 5 2 5... ae TGs “oy phoes 


Table 12-1. Palette Function Summary. 


Palette Function Descriptions na 
This section contains the detailed descriptions of the color palette functions. wtih cok 


__ Tight to the left of the client area in 
~ less than one second. This example. ; 


‘The movement is caused by rapidly. . 


OWin 2.0 @Win3.0 mWin3.1 
Purpose Rapidly changes the color of ‘objects mantel with colors from a logical palette. . 
Syntax void AnimatePalette(HPALETTE hPalette, WORD wStartIndex, WORD wNumEntries, 
. -  LPPALETTEENTRY IpPaletteColors); “4 
' Description’ Colors can be switched rapidly on the screen Dy. changing the hardware color palette. 
AnimatePalette() does this for items ina logical palette that have the PC_RESERVED flag (see 
CreatePalette() for the description of the LOGPALETTE data structure). 
Uses Moving objects on the screen can be simulated by prepainting the objects in the background 
color (usually white), and then cycling through each object from white, ‘to color, to white. 
Returns No returned value (void). i 
See Also CreatePaletteQ)...: -- 
Parameters 
hPalette HPALETTE: A handle to the ological palette returned by CreatePalette(). 
wStartIndex ‘WORD: The number of the first entry in the logical palette tochange. —~ 
wNumEntries -. , WORD: ‘The number of entries i in the logical palette to change. 
lpPaletteColors LPPALETTEENTRY: A pointer to an array of PALETTEENTRY data structures containing the 
new color values to use. See CreatePalette() for the structure definition of PALETTEENTRY. 
Example This example creates a rapidly moving red bar. The bar starts at. the left side of the client area 


(see Figure 12- 3). When the user clicks the “Do ith menu item, the bar appears to move from the 


will only work on a system that sup- <2 _ generic 


. ports over 128 simultaneous colors. .. 


Do It! Quit 


changing the color of a series of 128 


rectangles placed ahead of time in Figure 12-3. AnimatePalette() Example. 


,. «the client area. To. begin, only the 


leftmost rectangle is colored red. The rest are colored white, so they are not visible. The color of 
each successive rectangle is changed to red using AnimatePalette(). This is much faster man 
painting each rectangle using the'Rectangle() function. 
'~ Inthe source code, the WM. CREATE section creates the logical palette. The 128 colors are 
all initialized to white, except for the first one, which is red. The WM_PAINT section paints all 
-128 rectangles on the client area; even though only the first one is initially visible. This technique 
allows AnimatePalette() to change the color of each rectangle without the delay of painting. 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ss 


PAINTSTRUCT : ps; 

static HPALETTE : hPal ; - + 

HDC hoc >; 

“HBRUSH hBrush ; 

static LOCALHANDLE hLocPal ; 

static PLOGPALETTE pLogPal ; 

int i; 

static int : nNunColor ; 

switch CiMessage) /* process windows messages */ 
{ 


case WM_CREATE: 
i nNumColor = 128 ; 
ae hLocPal = LocalAlloc (LMEM_MOVEABLE, sizeof (LOGPALETTE) * 
aa nNumColor * sizeof (PALETTEENTRY)) ; 
pLogPal = (PLOGPALETTE) LocalLock (hLocPal) ; 
pLogPal->palVersion = 0x300 ; /* for windows 3.0 */ 
pLogPal->patNumEntries = nNumColor ; 
‘for (Ci = 0; i <nNumColor ; i++) 


£ 
pLogPal->palPalEntry Cil.peRed = 255 ; : 
pLogPal~->palPalEntry CiJ.peGreen = (1 == 070: 255); 
plogPal->palPalEntry CiJ.peBlue = (i == 020: 255) > 
plogPal->palPalEntry-Cild.peFlags = PC_RESERVED ; 

} 


hPal = CreatePalette (pLogPal) y 
LocalUnlock snbock al? 7 
break ; 
case WM_PAINT: 
BeginPaint (hwnd, &ps) ; 
SelectPalette (ps. hdc, hPal, FALSE) ; 
RealizePalette (ps.hdc) ; 
SelectObject (ps.hdc, GetStockObject CNULL_PEN)) ; 


for (i = 0 ; i < nNumColor ; i++) 

{ 
hBrush = CreateSolidBrush (PALETTEINDEX (i)) >; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, i * 4, 0, Ge * 4) + 25, 50) > 
SelectObject (ps.hdc, GetStockObject (WHITE_BRUSH)) ; 
DeleteObject ChBrush) ; 

} : 

’ EndPaint (hWnd, ups) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam). 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
pLogPal = (PLOGPALETTE) LocalLock ChLocPal) ; 
for (i = 0 ; i < nNumColor ; i++). 
{ n> 2 


pLogPal->palPalEntry Cil.peGreen = 255 ; 
plogPal—>palPalEntry Cil.peBlue = 255 ; 
if (i < nNumColor - 1) 


{ 
pLogPal->palPalEntry. Ci + 1j.peGreen 
plogPal->palPalEntry Ci + 1].peBlue = 
}. : 
else 
{ 
pLogPal—->palPalEntry COJ.peGreen = 0 
pbograt,palhelentry CO}.peBlue = 0; 
} 


AnimatePalette (heat, 0; nlumcolor; 
pLogPal->palPalentry) ; L 
} } . 
_ LocalUniock ChLocPal) ; 
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break ; 
case IDM_QUIT: /* send end of application message */ 
peser oye don ChWnd)-; 
break ; 
} 
break ; 
case WM_DESTROY: '/* stop application */ 


LocalUnlock (hLocPal) ; 
LocalFree ChLocPal) ; 
DeleteObject (hPal) ; 
PostQuitMessage (0) ; 


break ; 
default: ; /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} ; 
return (OL) ; 
} 
CREATEPALETTE . OWin2.0 w#Win30 weBWin3.l 
Purpose Creates a logical palette. . 
Syntax HPALETTE CreatePalette (LPLOGPALETTE /pLogPalette); 
Description This function reads the data in the lpLogPalette data structure and creates a color palette based 


on those values. The LOGPALETTE data structure is defined in WINDOWS.H as 


/* Logical Palette */ 
typedef struct tagLOGPALETTE_XE “LOGPALETTE"_ { 


WORD palVersion; ‘ 
WORD palNumEntries; 
PALETTEENTRY palPalEntry(1]; 
} LOGPALETTE; 
typedef LOGPALETTE *PLOGPALETTE; 
typedef LOGPALETTE NEAR *NPLOGPALETTE; 
typedef LOGPALETTE FAR *LPLOGPALETTE; 


The palVersion element specifies the Windows version number. 0x800 is used for version 3.0. — 
palNumEntries specifies how many entries there are in the palette. Each entry is a 
PALETTEENTRY data structure, also defined in WINDOWS.H. 


typedef struct tagPALETTEENTRY_XE “PALETTEENTRY"_ ¢ 


BYTE peRed; 

BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 


} PALETTEENTRY; 
typedef PALETTEENTRY FAR *LPPALETTEENTRY; 


The color name elements are allowed to range from 0 to 255. The peFlags element is normally set 
to zero, but can contain one of the values listed in Table 12- 2. 


PC_EXPLICIT Specifies that the low-order word is a direct index to the hardware palette. 


PC_NOCOLLAPSE The color will be placed in available system palstte locations, but not matched to an existing 
color in the system default palette. If the system default palette is full, the color is matched 
normally. 

PC_RESERVED Specifies that the palette element will be used for palette animation. This prevents other 


windows from matching colors using this entry. Only unused,palette entries will be filled with this 
flag set. If ail palette entries are taken, the entry will not be available for animation. 


Table12-2. PALETTEENTRY Flags. 
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Uses 


_ Used to create color palettes. Before the palette. can be used, it must be selected into the device 


~~ eontext with’ SelectPalette() and mapped:to the hardware palette using RealizePalette(). 


Returns 


See Also 


Parameters 
lpLogPalette 


 nbemsua 


Related Messages 


‘Example "© 


HPALETTE, a handle to the palette created. The returned vas normally is stored as a static 
variable. 


DeleteObject(), SelectPalette(), RealizeFalette() 


LPLOGPALETTE: A pointer to a LOGPALETTE data structure. defining the palette. A memory 
area large enough to hold the LOGPALETTE data structure and all of the PALETTEENTRY struc- 


tures for’each. color must be allocated and initialized before CreatePalette() is called. Once 


CreatePalette() has been used to register the new palette, the memory for the LOGPALETTE 
data structure and PALETTEENTRY items can be freed to the system. Fre 


WM_QUERYNEWPALETTE, WM_PALETTECHANGED 


* This example shows the creation of a logical palette. The number of available ’colors is deter- 


mined with two calls to GetDeviceCaps(). Temporary local.memory is.allocated to hold:the pal- 
ette during creation using LocalAlloc(), The color yalues for each palette entry are distributed to 


. , cover the size of the palette. The handle ¢ to the palette created i is stored i ina static variable hPal. 
piers Once the palette is created, the. meniory ‘used to, build thé palette can be released. ° As 


‘When a WM" “PAINT message is received, the program displays all of the colors by using the 
palette to create colored brushes that fill the rectangles drawn. Note that each brush.created 
must be removed from the device context before it can be deleted. ‘It is removed by selecting a 
stock brush into the device context, displacing the colored brush out of med device context. The 
palette is deleted when the programexits, (<5) :2sys000 ees : 


Long FAR PASCAL WndProc CHWND hWnd, SnaaneS iMessage;" ORD: MEE any LONG Param): 
{ 


Bee aay ar ear the Seah on TET 


PAINTSTRUCT ps; Cae, Sage 
HDC. - | WDC; ee a * At : 

OE statio! CHPALETTE: os ppaly SERIE ISS Sapo SUR SME oe agate ae oe 
op) t.. HBRUSH, Bey, See <peruen = hit Daher seGhwhh 3,8. NE 

LOCALHANDLE oo toca st 

PLOGPALETTE "  pLogPal’; es eek PEL 

int i, j,k, ‘Nunca, nNURE Cee petues, Green, nted:7 

static int 7 nfreeCol:; : oe 4 

switch (iMessage) —~ /*® process windows fieseaces */ 

{ 7 Woe initieciy 4 


case WM_CREATE: 
hDC = GetDC (hWnd) ; 
nNumCol = GetDeviceCaps (hDC; SIZEPALETTE) ; 
nNumRes = GetDeviceCaps Choc, NUBRESERVED: 2 
wei MEreeCol:= nNumCol - nNumRe's i TH ‘ 
"ReleaseDC. ChwWnd, hdc) ; vette pith vinta MR ah eos 
if CnFreetol’s= 216) °" 7* 2465 6 ‘cubed */ 
cone os os NRed = nGreen-=.nBlue = 6 7-00. +. ceils 8 ita eee 
else oF (nFreecot >= 16) 
Ler 


rpnadse eres 
nBlue | = ies ae 


250 z 


BR Pg a tase 
Dt AA ee ApEn ane ee ee ee ae ee 
Anodic = nereen = nBlue = 2; : 


nrecras = LocalAlloc (LMEM |_ MOVEABLE, sizeof - CLOGPALETTE). *. Shey 
bee 2 “nFreeCol: * sizeof (PALETTEENTRY))-; _ 
“ot, plLogPal.= (PLOGPALETTE) .LocalLock: (hLocPal) ; 
vo, .pLogPal->palVersion = 0x300 ; de for vandove 3.0 */ 
~~pLogPal- >palNumEntries = nFreecol ; Wo : 
for (i =O; i <nRed ; i++) © a ar rr een 14 ia 
{ : SOR GS aR UN LEO igen VES 
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for (j = 0.7 j <.nGreen;.jtt) fo ede 8: os 
: 


for (k-= 0 7.k'< nBlue. 5: k++) 

{ 
pLlogPal~>palPalEntry Cid. -peRed = ees 

i * (256 / mRed) yoo. Ue 

pLogPal->palPalEntry cil. peGreen = 
; “if * (256°/ nGreen) - 
pLogPal- >palPalEntry Cid, peBlue = 
“Ki® (256 / nBlue) ; 
ploupel-zpatratentry Cid. -peF Lags =0; 

} er 


Pua Ti, gests Wa yi eee, ge SS RG igs ots Sivet gS 


3 

hPal = Createpa latte (pLogPal) ; 

LocalUnlock ChLocPal) 7 bh iE sel) Ba 

pea lFree Cnbectal) 2 

: break ; ori oe Tate 

case WM_PAINT: , 

BeginPaint (hWnd, &ps) ; 

SelectPalette. (pss hdc, hPal, FALSE): ; 

RealizePalette (ps.hdc) ; 

for(i =O; i1< nFreecol:-s itt)? Te a sagt anes 

{ ee ee 

hBrush = CreateSolidBrush (PALETTEINDEX ay : ee "h 

* SelectObject (ps.hdc,; ag ay ere CS TIT 
--Rectangle (ps. hdc, i * 5, 0, (i * 5) + 5. 400) : 
; SelectObjeét (ps. hdc, Getstockobject (BLACK | BRUSH)) ; 
: Deletedbject ChBrush) ; : : 

7 

“EndPaint, ChWnd,, &ps) ; ihn ys. tas ae 

break ; 5 : A gk eee | Se ea CUS ae 

case WM_ COMMAND: cin _/* process.menu-items:*/ ° .: 
, _switch (wParam) a ee hae ei. & 


a pH ES Mad 


“case IDM. ‘QUIT: re pea /* send end:of‘application message */ 
“BestroyWindow (hWnd) ; ros 
Saget : heen 
“break ; oe oe 
‘case, WM_ DESTROY: 2 ]*: ‘step application xf 
DeleteObject ChPal) . : 
PostauitMessage., (0) ; 


‘break ; en 
detautes fk, default: windows message processing */ 
return berwindouProc ChWnd, wMessage,. wParam, . lParam) ; 
} ; 

. » SoperurmCOb per FF Sate ete OE te I oO 
GrtNEARESTPALETTEINDEX | - ee eat Win 2.0 Win8.0° > Win 3.1 
Purpose Finds the palette entry number that most alee wmaibenee a given RGB, vale, Oe 
Syntax WORD GetNearestPaletteIndex(HPALETTE hPalette, DWORD erColor); 

Description In many cases, the system palette will not have an exact match to a given RGB color. This func- 
tion returns the palette item which most closely matches the color. This palette item may be far 
removed from the desired color: value, if the palette was created mt a Narrow. tang? of colors. 

Uses Determining if colors in the logical palette need to be changed. 4 

Returns WORD, the palette item number that i is the closest match to the desired RGB value, 

See Also GetNearestColor(), PALETTEINDEX(), PALETTERGB 0; SetPaletteBniies() 

Parameters 

hPalette HPALETTE: The'handle to the logical palette returned by i GiealePaltte). 


635 


WINDOWS API BIBLE. 


- PALETTEENTRY data structures. 


COLORREF: The desired 32-bit color value. Use the RGB() macro to specify this value. 


crColor 

Example See the example under PALETTEINDEX(). 

GETPALETTEENTRIES ~ OWin2.0 mWin30 mWin3.l 

Purpose Determines the color values for a range of entries in a logical palette. 

Syntax - WORD GetPaletteEntries(HPALETTE hPalette, WORD wStartIndex, WORD wNumEntries, 
LPPALETTEENTRY lpPaletteEntries); 

Description This function will retrieve the RGB color values and flag value for each entry i in acolor palsies: 

Uses Determining the color of a specific index value in the color palette. 

Returns WORD, the number of entries retrieved. 

See Also PALETTEINDEX(), PALETTERGB(), GetSystemPaletteEntries() 

Parameters 

hPalette HPALETTE: The handle to the palette, returned by CreatePalette(). 

wStartIndex WORD: The number of the first palette entry to start with, 0 for the first. 

wNumEttries WORD: The number of entries to read. 

lpPaletieEntries | LPPALETTEENTRY: The address of 


an array of at least wNumEntries - 


See CreatePalette() for the struc- 


. ture definition of PALETTEENTRY. 


If you use a local variable array to 
hold this data, make sure the stack 
is sized large enough to hold the 
data. 


; Entry 0= Red 0, 
Entry 1 = Red 1, 
Entrv 2 = Red 2, 
Entry 3 = Red 3, 


Entry 4 = Red 4, 
Entry 5 = Red 5, 
Entrv 6 = Red 6, 
Entry 7 = Red 7, 


Green 0, Biue 0 
Green 4, Blue 8 
Green 8, Blue 16 
Green 12, Blue 24 
Green 16, Blue 32 
Green 20, Blue 40 
Green 24, Blue 48 
Green 26, Blue 56 


Related Messages WM_QUERYNEWPALETTE, 
WM_PALETTECHANGED _ 


This example creates a palette with 
216 entries, and then displays both 
the numerical values and a colored 
rectangle for each. (See Figure 12- 
4.) Painting occurs well beyond the end of the client area, so only part of the palette i is visible. On 
the screen, the rectangles to the right of the numeric values show the specified colors. 


Entry 8 = Red 8, Green 32, Blue 64 
+ Entry 9 = Red 9, Green 36, Blue 72 
Entry 10 = Red 10, Green 40, Blue 


Example 
Figure12-4. GetPaletteEntries() Example. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT . ps; 
static HPALETTE hPal ; 
HBRUSH hBrush ; 
LOCALHANDLE hLocPal i 
PLOGPALETTE pLogPal ; 
int ; i, j; 


static int 
static PALETTEENTRY 
char 


nFreeCol ; 
peEntry [256] ; 
cBuf [128] ; 


switch (iMessage) /* process windows messages */ 
{ ; 
: case WM_CREATE: 

nFreeCol = 216 ; 

hLocPal = LocalALloc CLMEM | MOVEABLE, Secor (LOGPALETTE) -* 


nFreeCol * sizeof (PALETTEENTRY)) ; 
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.pLogPal = (PLOGPALETTE) LocalLock ChLocPal) ; 
pLogPal->palVersion = 0x300 ; /* for windows 3.0 */ 
plogPal->palNumEntries = nFreeCol ; 

fpr (i =0 ; i <nFreeCol ; i++) 


pLogPal->palPalEntry Cil.peRed = i ; 
pLogPal->palPalEntry Cil.peGreen = (i * 4) % 256 ; 
plogPal->palPalEntry Cil.peBlue = Ci * 8) % 256; 
pLogPal->palPalEntry Cil.peFlags = 0; 
} ; . 
hPal = CreatePalette (pLogPal) ; 
LocalUnlock (hLocPal) ; 
LocalFree (hLocPal) ; 
break ; 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SelectPalette (ps.hdc, hPal, FALSE) ; 
see ees Cps.hde) ; 
naar alert ChPal, 0, nFreecot, peEntry) ; 
‘eh Ci=O0; i<j; it+) 
{ 
TextOut (ps.hdc, 10, 17 * i, cBuf, wsprintf (cBuf, 
"Entry 4d = Red “%d, Green 4d, Blue 4d", 
i, peEntryLil.peRed, peEntryLlil.peGreen, 
peEntrylil.peBlue)) ; 
hBrush = CreateSolidBrush Cee eernpe? (10) ; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 330, qi * ww +1, 360, 
Ci-* 17) + 16) ; 
SelectObject (ps.hdc, Getstockobiect CWHITE_BRUSH)) ; 
DeleteObject (hBrush) ; 
} 
EndPaint (hWnd, &ps) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 

} 

break ; 

case WM_DESTROY: /* stop application */ 
DeleteObject ChPal) ; 
PostaQuitMessage (0) ; 


break ; : 
default: - /* default windows message processing +t 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
} 
GETSYSTEMPALETTEENTRIES OWin2.0 mWin3.0 mWin3.] 
Purpose Determines the colors of each of the system palette items. 
Syntax WORD GetSystemPaletteEntries(HDC hDC, WORD wStartIndex, WORD wNumEntries, 
LPPALETTEENTRY [pPaletteEntries); 
- Description The system palette is a group of 20 colors that Windows uses for the default color scheme. All 


applications share the system palette. Entries in the system palette can be changed by calling 
SetSysColors(). All applications are notified of the change by a WM_SYSCOLORCHANGE mes- 
sage. They can then use GetSystemPaletteEntries() to determine the new system palette colors. 


Uses , Processing WM_SYSCOLORCHANGE messages, and determining the system palette entries for 
painting with pure colors. 
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Returns _WORD, the’ number of system eae. en- “—E Oars te 
tries retrieved. ee a ae SE cee ere: lage 
See Al GetPaletteE SysCol | aA Se 
eae ethalette teas Set yo on Entrv 0 = Red 0, Green 0, Blue 0 
Parameters ape Entry 1 = Red 128, Green 0, Blue 0 
: wees --f Entry 2 = Red 0, Green 128, Blue 0 
hDC HDC:.The device context handle. | Entry 3 = Red 128, Green 128, Blue 0 
-«-f Entry 4 = Red 0, Green 0,'Blue 128 
wStartIndex WORD: The first palette eiry to read: Zero Entry 5 = Red 128, Green 0, Blue 128 
forthefirstone. +. +... ..,. [Entry 6 = Red 0, Green 128, Blue 128 
. sq: Entry? = Red 192, Green 192, Blue 192 
wNumEntries WORD: The number of nitriles to er .. } Entry 8 = Red 192, Green 220, Blue 192 


. ] Entry 9 = Red 166, Green 202, Blue 240 
lpPaletteEntries ©LPPALETTEENTRY: A pointer to an array - | Entry 10 = Red 24 Green 96, Blue 192 
of at least wNumEntries PALETTEENTRY _Entrv.11 = Red 25, Green 100, Blue 200 


structures that will hold the data read from...) Entrv 12 = Red 26, Green 104, Blue 208 


the system palette. See CreatePalette() for : eee, ae ‘fed as oc 1 ae AN 


the structure definition for. PALETTE-  . |. Entry.15 =.Red 29. Green 116, Blue 232 


ENTRY. ‘| Entry 16 = Red 30, Green 120, Blue 240 
: oot | Entry 17= Red 31, Green 124, Blue 248 
Related Messages: WM_ ‘SYSCOLORCHANGE — us | Entry 18 = Red 32, Green 128, Blue 0 


Entry 19 = Red 33, Green 132, Blue 8 


Example ~~ This example, which is shown i in Figure 12- iy 
. 5;demonstrates how to dump the RGBcon-: Figure 12-5. GetSystemPaletteEntries() 
tent of each color in the system palette. : Example. 
These colors are the same ones that show. 
“2.152. up as pure colors in the Windows Control Panel Color: ‘application. 


long FAR PASCAL WndProc CHWND Mnee chsioned iMessage, | word wParam, LONG iparaw) 
{ : 


PAINTSTRUCT . ps te 

HBRUSH <:5 2 wat te tee hBrush ; iste AST IMT IE. 
int i, i; i on Meat! 

erat te. PALETTEENTRY peEntry C20] ; 

‘éhar: hp ofa ete ba oh. @Buf £128) po rf es lon ne, 

switch (iMessage) /* procéss' windows messages */ 


{ 
: case WM_PAINT: 
BeginPaint ‘ChWnd,. “@ps)'> oe 
j= GetSystemPaletteEntries (ps, hae; 0, 20;, rence 
for (i =0; 1< jy i++) 


Mes = 
cae Textout (ps: hde, 10, 17 * i, cBuf, wsprintf €cBut, 
"Entry zd = Red'%d, ‘Green 4d, Blue %d", 
» .. i, peEntrylil. peRed, peentryLid. peGhesn,: a 
. " . - peEntryLil.peBlue))-; - a . 
/hBrush = CreateSolidBrush: (PALETTEINDEX Ci)) ; 
SelectObject:(ps.hdc> ee 
Rectangle (ps.hdc, 330, (i * 17) +1, 360, R 
: Ci * 17) +°16) ; . 
...SelectObject (ps.hdc, Getstockobject! (WHITE: “BRUSH))’; 
-,DeleteObject ChBrush):;7.... |. ek Ts sa ioe 
ss } 
Se at Bete Soo endPaint ChWnd,.&ps) 23.007: cca aint Piatt, eta 
break ; Walang Dates Sg pag Pe i. 
is Other program lines | 
GurSysremPanerréUse es Ae eh ae ake 1. Win 9 0 “min 3.0 mWin3.1 
Purpose _ ii w __, Determines if an application can change the system palette.” ieee ae 
Syntax... WORD GetSystemPaletteUse(HDC. ADC, WORD wllao) re 


wpb ured 
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Description ‘The system palette contains 20 color entries that Windows uses to draw objects, including dith- 
vse. * aved ‘color brushes. Normally, these entries'are not changed if a logical palette is realized. 
= GetSystemPalettel’'se() will determine if the Values can pe changed. 


Uses) ‘Used | prior to changing the system palette. 


Returns _ WORD, one of the values in Table 12-3. 
Vv : "Meaning eee 
SYSPAL_NOSTATIC The system palette contains no static colors. 
SYSPAL_STATIC The system palette contains static colors which will not change when an explain calls 


RealizePalette(). 


Tablel2-3. GetSystemPaletteUse() Flags. 


See Also Poe Wachee 0 

Parameters 

hDC HDC: The device context handle 

wUndoc WORD: An undocumented word value. Set this value to SYSPAL _NOSTATIC, 


Related Messages WM_ SYSCOLORCHANGE » ae 


PALETTEINDEX. onan avinay a 3.1 
eee Directly specifies a logical palette color. 9. 
Syntax COLORREF PALETTEINDEX (int Palettelndea’);- 


Description This macro returns the 32-bit color value for a specific entry i in the logical palette. The macro is 
_ defined 1 in WINDOWS. H as follows: . 


ddefine PALETTE INDEX (4 i) : CCDWORD) (0x01000000. i cwoRD? Gi) y” 
Note that the 32-bit color value for indexed colors includes a 1 in the high-order byte. 


Uses Directly specifying the use of a palette color i in creating a brush, pen, or text color. 
Returns COLORREF, the 32-bit colorvalue. 0: ne. is ~ 
See Also ~~ PALETTERGB(), RGBQ) ; Sees fae, 
Parameters sk ota Si apa - 
nPaletteIndex int: The number of the entry in the | = SOT ethane 

logical palette. Zero for the first Do lt! Quit 

item; ete. . . +: BBB PALETTEINDEX (62) 

. a gs PALETTERGB (200, 200, 255) -> 248; 240, — 

Example This example: (see Figure 12: 6) cre: A RGB (200, 200, a5) )- 


ates a custom palette when the pro-. 

gram starts: When:a: WM_PAINT © Figure 12-6. PALETTEINDEX( ) and ees ) 

message is received, three colored’ ’ pase 

rectangles are drawn using three. . 

different ways to specify a color: The first one is s dra awn mby specifying a palette index using PALET- 
~  TEINDEX(). The second one is drawn with PALETTERGB(),’ which picks the closest palette color 

to the requested RGB value. In this case, there is not a good match. The actual RGB value for the 

- palette selection is extracted with GetNearestPaletteIndex(). and displayed to the far right in the 
figure. The last rectangle is drawn. with a color value spécified with the RGB(Q) macro, which 
creates a hatched brush that simulates the Ueiee oe by dithering. 


oh 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
t 


Note in the example code that the previous brush is deleted by deleting the returned value 
from SelectObject(). SelectObject() returns a handle to the last similar object selected. This is a 
convenient technique because it is not possible to remove the object from memory until it is 
selected out of the device context. Selecting the new object pushes the old one out, ready to be 
deleted. 


PAINTSTRUCT ps ; 


static HPALETTE hPal >; 
Hoc hoc ; 
HBRUSH ' hBrush ; 
’ LOCALHANDLE neeepat’ e : 
PLOGPALETTE plogPal ; . se 
int ty nNumcol, ntumRes, nColor ; 
Static int '  nFreeCol ; 
DWORD dwColor ;_ 
char’ cBuf C128] ; 
switch (iMessage) /* process windows messages */ 
{ 


case WM_CREATE: r= 
hDC = GetDC ChWnd) ; 
nNumCol = Seenudeockvs ChDC, SIZEPALETTE) ; 
nNumRes = GetDeviceCaps ChDC, NUMRESERVED) ; 
nFreeCol = nNumCol - nWuane® . 
ReleaseDC ChWnd, hDC) ; 


hLocPal = LocalAlloc (LMEM_MOVEABLE, sizeof (LOGPALETTE) * 
nFreeCol * sizeof (PALETTEENTRY)) ; 

plogPal = (PLOGPALETTE) LocalLock ChLocPal) ; 

pLogPal->palVersion = 0x300 ; /* for windows 3.0 */ 

pLogPal->patNumEntries = nFreeCol ; 

for (i = 0 7 i1<nFreeCol ; i++) 

{ 


pLogPal->palPalEntry Cil.peRed = (i * 4) % 256 ; 
pLogPal->palPalEntry Cil.peGreen = Ci * 8) % 256 ; 
pLogPal->palPalEntry Cil.peBlue = (i * 16) % 256; 
plogPal->palPalEntry Cil.peFlags = 0 ; 

} ; 

hPal = CreatePalette Sphogk aly 3 

LocalUnlock ChLocPat) ; 

cave caedicha ChLocPal) ; 

break ; 

case WM_PAINT: 

BeginPaint (hWnd, &ps) ; | 

SelectPalette (ps.hdc, hPal, FALSE) ; 

RealizePalette (ps.hdc) ; / 


= GetNearestPaletteIndex ChPat, 
RGB (200, 200, 255)) ; 
hBrush-= CreateSolidBrush (PALETTEINDEX (i); 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, 0, 0, 30, 17) $ 
TextOut (ps.hdc, 40, 0, cBuf, wsprintf (cBuf, 
“PALETTEINDEX (%d)", 1)) ; 


hBrush = CreateSolidBrush ( 
PALETTERGB (200, 200, 255)) ; 

DeleteObject (SelectObject (ps.hdc, hBrush)) ; 

Rectangle (ps.hdc, 0, 20, 30, 37) ; 

dwColor = GetNearestColor (ps.hdc, | 
PALETTERGB (200, 200, 255)) ; 

TextOut (ps.hdc, 40, 20, cBuf,.wsprintf (cBuf, 
“PALETTERGB (200, 200, 255) -> Xd, Ad, Ad", 
GetRValue (dwColor), GetGValue (dwColor), 
GetBValue (dwColor))) ; 
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/ 


hBrush = CreateSolidBrush (RGB (200, 200, 255)) ; 
DeleteObject (SelectObdject (ps.hdc, hBrush)) ;. 
Rectangle (ps.hdc, 0, 40, 30, 56) >; 

TextOut (ps.hde, 40, 40, “RGB (200, 200, 255)", 19) ; 
EndPaint ChWnd, &ps) ; — 

DeleteObject (hBrush) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) : 
{ 
case IDM_DOIT: /* User hit the “Do it" menu item */ 
InvalidateRect (hWnd, NULL, TRUE) ; 
break ; 
case IDM_QUIT: : /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: . /* stop application */ 


DeleteObject ChPal); ; 
PostQuitMessage (0) ; 
break ; . 
detault: /* default windows message precessing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return COL) ; 
} 


PALETTERGB OWin2.0 mWin30 mWin3.l 
Purpose Retrieves the color closest to the desired RGB color from the logical palette. 

Syntax COLORREF PALETTERGB (BYTE cRed, BYTE cGreen, BYTE cBlue); 

Description This macro retrieves the logical palette color closest to the desired RGB color. The macro is 


defined in WINDOWS.H as follows: 


Hdefine PALETTERGB(r,g,b) (0x02000000 | RGB(r,g,b)) 


Note that the high-order byte is set to a value of two. 


Uses Used with devices that support a large number of colors. In thes2 cases, it becomes difficult to 
keep track of the individual palette index values. PALETTERGB() also has the advantage of be- 
having similarly to the RGBQ) macro that defines dithered colors. 


Returns COLORREF, the 32-bit color value. 

See Also PALETTEINDEX(), RGB() 

Parameters 

cRed_ BYTE: The red element of the color, 0 to 255. 

cGreen BYTE: The green element of the color, 0 to 255. 

cBlue BYTE: The blue element of the color, 0 to 255. 

Example See the previous example under PALETTEINDEX(). 

REALIZEPALETTE OWin2.0 mWin30 mWin3.1 
Purpose Maps the logical palette selected into a device context to the hardware palette. 

Syntax int RealizePalette (HDC hDC) ; . . 

Description Before palette colors can be used, the palette must be created with CreatePalette(), selected 


into the device context with SelectPalette(), and “realized” using RealizePalette(). 
RealizePalette() sets the hardware palette entries to the values specified in the palette selected 
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Uses 


Returns 
See Also 


Parameters 
hDC 


into the:device context.:Realizing a palette has system-wide effects, as all windows are painted 


using the palette: entries. Priority is ‘given-to ‘the active window for use of the palette colors. 


Inactive windows can use remaining free palette entries. “Any additional colors that are needed 
will be matched to the closest palette entry: available: ra 

Windows sends all applications runnirig on the system‘a WM. : PALETTECHANGED message 
after RealizePalette() is called. This allows applications that, do Rot. have.the input focus to real- 
ize their logical palettes using the new system palette values. : 


...» This function must be used.before attempting to paint with the palette colors. The function also 


is called when the’ application receives a WM - _QUERYNEWPALETTE message. 


-: :.. Int, the number of entries in the logical palette that. were changed. 


CreatePalette(), SelectPalette(), DeleteObject(), UnrealizeObject() 


HDC: The device context handle. 


Related Messages WM_QUERYNEWPALETTE, WM _PALETTECHANGED 


Example. Es See the comple: under Ceara: 

ReseeP ere OWin2.0 mWin30 mWin3.1 

Purpose Changes the size of a logical palette, — 

Syntax . ie BOOL ResizePalette(HPALETTE hPalette, WORD nNumEntries), pees : 

Description © ae This function allows the size ofa logical palette to be changed after the palette has been ‘created: 
Ifthe palette i is reduced in size, the remaining entries: are not affected. a the palette is increased 
in size,:the new entries are ‘all'set to zero. : 

Uses" °°" Bliminates the need to creaté a‘new ‘palette if the sn at crtees mis as the program 
runs. i De Ga EE DT Ae rh peerage abe 

Returns BOOL. TRUE if the palette was resized, FALSE on error. .... : barns 2 ae rey SS ae Calis 

See Also SetPaletteEntries(), CreatePalette(), ae ne hg e 

Parameters :p:.0020 0) eccryenls ge te 


BPaletle sscysiay ot 


situbnieias: 


 HPALETTE: The palette handle rtumpd ty Gretel). : ae: : : od 
WORD: The new number of elements in the Balsttes" ; 


Related Messages WM_PALETTECHANGED 


Example 


Anthis example, the starting palette is as large as possible. Every time the user clicks the “Do: Ae 
menu item, the palette is reduced) in size by 50%. Sick ae ace 


long FAR PASCAL WndProc CHWND hWnd, unsigned inessace, WorD wParam, Lone param) 
{ eH Dh 


rie rere 3 fd 


PAINTSTRUCT PSi : rT ere 
HDC : . “hoes ST ETE aie, MEE EE ESE oa REEL SUS pb de OR eh 
static HPALETTE sssahbaled to Be ee ee ree oe ee eee 
HBRUSH 7" “hBrush'; paint ia Seaie a 
LOCALHA Oe ; hLocPal ; 

ee PLOGPALE ee ce fe stonpats 

eo int 4 sigan et oa tote Cyt tliges nNumcol nNumRes ; OT ae 
static Sthe Bip age Bathe Aa fine k nFreecol.; : 
switch (iMessage) /*. process ‘windows messages, */ 


es i “Case we ‘CREATES “iog-tfii oih ae ae ae Ba ei aaa bivhedts hea eff One eae, 


» + -hDC = GetDC Chwnd). 3 i, 
Fi ie nNumCol = GetDeyi cecons choc, ‘SIZEPALETTE) ; 
““"nNumRes =-GetDeviceCaps: ChDC; NUMRESERVED) ; 
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_nFreeCot = nNumCol -. MhumRess cz 
Releasedt Chin, hoc) ; 


“nigePal = LeeaL Attar CLMEM C MOVEABLE: sizeof LOGE ALE TIED * 
nFreeCol * sizeof (PALETTEENTRY)) ; wie 
segpal = CPLOGPALETTE) bocathock. Chiochats=: Sey es 
pLogPal->palVersion = 0x300 ; oe for windows 3. 0 ee 
. pLogPal->palNumEntries = nfreecol ; i 
for (1 =0; i < nFreeCol ; 7 itt) 


t 
sthapatsSaatheleneny Cid. steeds 0: +e 
pLogPal->palPalEntry Cil.peGreen = 0 ; 
pLogPal->palPalEntry Cild.peBlue = i * “(256 / nFreeCol) - 
pLogPal->palPalEntry Cid. peFlags =O; 


hPal = CreatePalette (pLogPal) i. 
LocalUnlock ChLocPal) 7 
‘ Local Free ChLocPal) ; 
break ; od - 
case WM_PAINT: , , 
BeginPaint: (hWnd, &ps) ; ei pesticide eM, yelthas 
SelectPalette (ps.hdc, pal, FALSE) ;. - vo 
RealizePalette (ps.hdc) ; oe 
for (i= 0 ;.1.< nFreeCol e itt) 


{ 
pe hBrush = - CreateSotidBrush (PALETTE INDEX aoe 
SelectObject.(ps.hdc, hBrush) ;: : 
. Rectangle (ps.hdc, i * 5, 0, (i * 5) + 5, 100) s 
'-SelectObject (ps.hdc, Getstockobject (BLACK_BRUSH)) ; 
_ DeleteQbject (hBrush) ; 
} 
EndPaine: ChWnd, ‘&ps) ; 
. break ; 


case WM_COMMAND: /* process menu items */ 
switch (wParam)... 9. 0... ES tata. © Suntec fod 
t wn Peaed 


case IDM_DOIT::...: °«. «.:/* User hit.the'"Do.it" menu. item */ . ,: 
nFreeCol /= 2; /* cut num colors in half, ae 
ResizePalette: “ChPak;: nFreeCol) ; 0 0: : 
rivet iaarebect (hWnd, NULL, TRUE) Beyer eeipe | 


‘break ; 

“case ‘IDM! “QUIT: Lr i hal eend end of epRvi carte) message */ 
DestroyWindow (hwnd) ; : : Sous 
break ; 

+ eye. 

break ; 


“ease WM DESTROY: Wore Git 1b /® stop application PEL the 


peletabbiece (hPal) ; 
|, PostauitMessage (0) ; 


‘break ; : 
rdefaultr.) 0.05 .. ot~*- default windows message: processing: os 
return pafWindowProc ChWnd, iMessage, wParam, lParam) ; 
} 
return (QL) ;. 
} 
SELECTPALETTE ee OWin2.0 . Win 3 3.0  mWin3.1 
Purpose Selects a color palette into a device context. Boh 
Syntax HPALETTE SelectPalette (HDC ADC, HPALETTE hPalette, BOOL bForceBackground) ; 5 
Description This function is the analog to SelectObject(); except that it only works for palettes. The hPalette 
parameter is the handle returned when the palette was created with CreatePalette(). Selecting a 
palette into the device context does not immediately make the colors available. RealizePalette() 
must be called to map the selected palette to the hardware so that the colors are available. 
Uses Used in WM_PAINT logic that uses the color palette to define colors. ” - 
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Returns HPALETTE, the old logical palette displaced from the device context. NULL on error. 
See Also CreatePalette(), RealizePalette(), DeleteObject(), UnrealizeObject() 

Parameters 

hDC HDC: The device context handle. 

hPalette HPALETTE: The handle of the logical palette returned by CreatePalette(). 


bForceBackground BOOL: Specifies if the logical palette is to be in effect if the window does not have the input 
focus. TRUE if it is to be in effect, FALSE (the normal case) if not. 


Related Messages WM_QUERYNEWPALETTE, WM_PALETTECHANGED 


Example See the example under CreatePalette(). 
SETPALETTEENTRIES : OWin2.0 mWin3.0° mw Win3.1 
. Purpose Changes the color values in a logical palette. 
Syntax WORD SetPaletteEntries(HPALETTE hPaletie, WORD wStartIndex, WORD wNumEntries, 
LPPALETTEENTRY [pPaletteEntries), 
Description This function is useful after a palette has been created. It allows the saletis colors and flag values 


for entries in the palette to be changed without creating a new palette. The changes take effect 
once the palette is realized with RealizePalette(). 


Uses This is the most efficient way to change a color palette while an application is running. 


Returns WORD, the number of entries set in the logical palette, zero on error. 
See Also CreatePalette(), RealizePalette(), SelectPalette(), DeleteObject() 
Parameters = 

hPalette HPALETTE: The handle to the palette returned by CreatePalette(). 
wStartIndex WORD: The number of the first palette entry to change. 
wNumEntries WORD: The number of entries to change. 


lpPaletteEntries LPPALETTEENTRY: A pointer to an array of PALETTEENTRY data structures. See 
CreatePalette() for the structure definition for PALETTEENTRY. There must be at least 
wNumEntries array elements. 7 


Related Messages WM_QUERYNEWPALETTE, WM_PALETTECHANGED 


Example This program initially creates a palette of blue shades and paints them across the top of the client 
area. The number of colors is set to use every free color, excluding those dedicated to the system 
palette. When the user clicks the “Do It!” menu item, the palette is changed to shades of red. This 
change is not instantly visible because the palette i is not realized until the next WM_PAINT mes- 
sage is processed. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . 


PAINTSTRUCT ps ; 

HDC HDC ; 

static HPALETTE hPal ; 

HBRUSH ; hBrush ; 

LOCALHANDLE hLocPat ; 
PLOGPALETTE pLogPal ; 

int i, nNumCol, nNumRes ; 
static int nFreeCol ; 

Static PALETTEENTRY ' pePal€nt £256] ; 
“switch CiMessage) /* process windows messages */ 
a 


case WM_CREATE: 
hDC = GetdC ChWnd) ; 
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nNumCol = GetDeviceCaps (hDC, SIZEPALETTE) ; 
nNumRes = GetDeviceCaps ChDC, NUMRESERVED) ; 
nFreeCol = nNumCol ~— nNumRes ; 


ReleaseDC (hWnd, hDC) ; 


= LocalAlloc (LMEM_MOVEABLE, sizeof (LOGPALETTE) * 
nFreeCol * sizeof (PALETTEENTRY)) ; 

pLogPal = (PLOGPALETTE) LocalLock (hLocPal) ; 
pLogPal->palVersion = 0x300 ; /* for windows 3.0 */ 
pLogPal~>palNumEntries = nFreeCol ; 


hLocPalt 


for (Ci = 0; i<nFreeCol ; i++) 

{ * 
pLogPal->palPalEntry Cid.peRed = 0 ; 
pLogPal~->palPalEntry Cil.peGreen = 0 ; 
pLogPal->palPalEntry Cil.peBlue = i * (256 / nFreeCol) ; 
pLogPal->palPalEntry Cil.peFlags = 0 ; 

} . 

hPal = CreatePalette (pLogPal) ; 


LocalUnlock ChLocPal) ; 
ocar Eres ChLocPal) ; 
break ; 


case WM_PAINT: 


case WM_ 


case WM_ 


default: 
} 2 
return (OL) ; 
) : 
-SetSysCo.ors 
- Purpose 
Syntax 


BeginPaint (hWnd, &ps) ; 
SelectPalette (ps.hdc, Pat, 
RealizePalette (ps.hdc) ; 


FALSE) ; 


for (i = 0; i < nFreeCol ; i++) 

{ . 
hBrush = CreateSolidBrush (PALETTEINDEX (€i)) ; 
SelectObject (ps.hdc, hBrush) ; 
Rectangle (ps.hdc, i * 5, 0, Ci.* 5) +5, 100) ; 
SelectObject (ps.hdc, Getstockvhject (BLACK_| BRUSH)) ; 
DeleteObject ChBrush) ; 

} 

EndPaint (hWnd, &ps) ; 

break ; 

COMMAND: 


/* process menu items */ 
switch (wParam) ; 


case IDM_DOIT: /* User hit the "Do it" menu item */ 


for (i = 0; i<nFreeCol ; i++) 
{ 
pePalEnt Cil.peRed = i * (256 / nFreeCol) ; 
pePalEnt Cil.peGreen = 0 ; 
pePalEnt Cild.peBlue = 0 ; 
pePalEnt Cil.peFlags = 0 ; 
} : 


SetPaletteEntries (hPal, 0, nFreeCol, pePalEnt) ; 
InvalidateRect (hWnd, NULL, TRUE) ; be 
break ; 

case IDM_QUIT: /* send end of application message */ 
DeleteObject ChPal) ; 

DestroyWindow (hWnd) ; 
break ; 

} 

break ; 

DESTROY: : 

PostQuitMessage (0) ; 

break ; 


/* stop. application */ 


/* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


mWin2.0 mWin3.0 


Changes the system colors used to paint window objects. 
void SetSysColors (int nChanges, LPINT IpSysColor’, DWORD FAR “ipColorValues); 
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Description The system colors define what colors Windows uses to paint objects like borders and buttons. 
Windows reads these values from the WIN.INI file on startup. The values can be changed using, 
_ the Windows Control Panel Color application. The values can be temporarily changed during a 
- Windows session by calling SetSysColors(). Use eee ee for permanent changes to 
the WIN.INI file. 


Uses | Not often used. Allows an application to change the colors of various Windows objects during the 
; session, without changing the default values. This affects every running application. 


Returns. No returned value. 


See Also GetSysColors(), GetProfilelnt(), GetProfileString(), WriteProfileString() 
~ Parameters , = . 
nChanges int: The number of color items to change. 
‘IpSysColor LPINT: A pointer to an array of at least nChanges int values. Each element of the array should be 


one of the values in Table 12-4. 


COLOR _ACTVEBORDER The active window border. 

COLOR: ACTIVECAPTION The active window caption. . 
COLOR_APPWORKSPACE The background color for MD! windows. 
COLOR_BACKGROUND The desktop color. - 


~COLOR_BTNFACE The button face. 
COLOR_BTNSHADOW | ~The edge of a button. 
COLOR_BTNTEXT The button text. 
COLOR_CAPTIONTEXT. —_—The text inside the caption bar. 
COLOR_GRAYTEXT The color.of grayed text, as used in disabled menu items. Set to 0 if the display does not 
“— support pure gray colors.: 
~ COLOR_HIGHLIGHT The highlighted control color. 


COLOR_HIGHLIGHTTEXT . The text color of a highlighted item in a control. ’ 
COLOR_INACTIVEBORDER — The color of an inactive window border. 

* COLOR _INACTIVECAPTION ‘The color of an inactive window caption. 
COLOR _INACTIVECAPTION “Color of the text i in an inactive caption. 


TEXT Wi n3.1) 
. COLOR_MENU’ : The background color for window menus. Se 
COLOR_MENUTEXT “The text color for menus. e 5: ‘ . \ . 
~~ COLOR_SCROLLBAR The scroll bar gray area. 
COLOR WINDOW . —__ The background color for windows. 
.COLOR_WINDOWFRAME ~— Thewindow frame. . 
~ COLOR_WINDOWTEXT ~The color of text in windows.. : 


Table 12-4, System C Colors. 


eater . -DWORD FAR *: A saintse) toa an array of DWORD vale containing the RGB values used to set 
each of the items specified in. the ety array. 


Related Messages WM. _SYSCOLORCHANGE - 
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Example - When the user clicks the “Do It!” menu item, two of the system colors are changed, the window 
background and the work space background colors. The changes are immediately shown on the 
screen when Windows updates all applications. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
see : 


Hoc hoc ; 


int nsverndes C2] = {COLOR_WINDOW, COLOR_| BACKGROUND} ; 
DWORD dwColors C2] = {RGB (240, 240, 255), a 
RGB (200, 210, 255)} ; 
switch (iMessage) /* process windows messages */ 
case WM_COMMAND: /* process menu items */ ° 
switch (wParam) 
case IDM_DOIT: /* User hit the "Do it" menu item */ 


hDC = GetDC (hWnd) ; 
SetSysColors (2, asysindex, dwColors) ; 
ReleasedC chung, hdc) ; 


break ; 
[Other program lines] 
SETS ysTEMPALETTEUSE a OWin2.0 mWin3.0 mWin3.1 
Purpose Allows modifications to the system color palette. 
Syntax WORD SetSystemPaletteUse(HDC DC, WORD wUsage); » 
Description Normally, Windows reserves 20 color values for use by all windows. This is called the system 


palette. SetSystemPa.etteUse() allows an application program to chane the system palette, or 
set the status back to the normal, fixed status. 

Uses" Changing the system palette may be a desirable way to extend color section when using a device 
that has between 16 and 64 colors. Above 64 colors, there are enough free colors that it is simpler 
to leave the system colors unchanged and add other colors as needed. 


Returns | . WORD, the previous system palette state, either PAL_NOSTATIC or PAL_: STATIC. See the defini- 


tion of these values in Table 12-5. ¢ 
See Also SetSysColors() 
Parameters 
hDC HDC: The device context handle. 
wusage WORD: One of the two values in Table 12-5. 


SYSPAL “NOSTATIC. The system palette is not static and will change when the program realizes a logical palette with _ 


RealizePalette(). A pure black and pure white value are always retained. 
SYSPAL_STATIC _ The system palette is static and will not be affected by realizing a logical palette with 


RealizePatette(). 


Table 125. SetSystemPaletteUise() Flags. 


Related Messages WM_SYSCOLORCHANGE 


Example This example changes the system palette when the user clicks the “Do It!” menu item. Before the 
ee changes are made, the existing palette is saved into an array dwOldColors[/]. When the user 

clicks the “Quit” menu item, the old palette is restored. Note that UnrealizeObject() is used to 

’ make sure that the palette changes are processed as if it were the first palette read into the 
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system. Also note that WM_SYSCOLORCHANGE messages are sent to-all applications for both 
changes as notification that the enysiem palette has changed. 
Hdefine NUMPALCOL 20 


Long FAR PASCAL WndProc (HWND hWnd, unsigned {Message, WORD wParam, LONG lParam) 
£ 


PAINTSTRUCT ps; 
HDC hDdc ; 
static HPALETTE hPal ; ; 
LOCALHANDLE hLocPal ; 
PLOGPALETTE : . plLogPal ; 
int i>; : 
. static int -., nColorindex CNUMPALCOL] ; 
static DWORD. dwOldColors CNUMPALCOL] ; 
switch CiMessage) /* process windows messages */ 
{ 


case WM_CREATE: ; ; 
hLocPal = LocalAlloc CLMEM_MOVEABLE, sizeof CLOGPALETTE) * 
NUMPALCOL * sizeof (PALETTEENTRY)) ; 
pLogPal = (PLOGPALETTE) LocalLock (hLocPal) ; 
pLogPal->palVersion = 0x300 ; /* for keiarnie 3.0 */ 
pLogPalt->palNumEntries = NUMPALCOL 4 
for (1 = 0 5 i < NUMPALCOL. ; i++) 


t . 
pLogPal->palPalEntry Cil.péRed = Ci * 128).% 256 ; 
plLogPal~>palPalEntry Cil.peGreen = Ci * 64) % 256 ; . 
plogPal->palPalEntry Cil.peBlue = ¢i * 32) % 256 ; 
pLogPal->palPalEntry Cil.peFlags = 0 ; 

} + 


hPal = CreatePalette (pLogPal) ; 
LocalUnlock (hLocPal) ; 


R LocalFree ChLocPal) ; 
break ; 39D: 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case. 1DM_ DOIT: /* User hit the "Do it" menu item */ 


“RDC = GetDC ChWnd) ; 
for €i-= 0 ; i < NUMPALCOL ; i++) 
{ 
nColorIndex Ci] 
dwOtdCotors Ci] 


i; 
GetSysColor ci) : 


} 
SetSystemPaletteUse (hDC,. SYSPAL_NOSTATIC) ; 
UnrealizeObject (hPal) ; 
SelectPalette (HDC, neah gs FALSE) ; 
RealizePalette ChDO) ; 

PostMessage (-1, WM __SYSCOLORCHANGE, 0, OL) ; 
Rebessent ChWnd, hDC) ; 


break ; 

case IDM_QUIT: /* eend end of application message */ 
DestroyWindow ChWnd) ; 
break ; 

} 7 

break >; 

case WM_DESTROY: /* stop application */ 
hDC = GetDC. (hWnd) ; ; > 


UnrealizeObject (hPal) ; 
SelectPalette (hDC, hPal, FALSE) ; 
RealizePalette (hDC) ; 
SetSysColors (NUMPALCOL, nColoriIndex, auotdcotors? iz 
SetSystemPaletteUse (hDC, SYSPAL_STATIC) ; 
PostMessage (-1, WM Loree ObORERANSE, 0, OL 
- DeleteObject (hPal) ; 
ReleaseDC ChWnd, hoc) ; 
Rostaultnessage eae 
return COL) ; 
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default: : /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
} * 
cd ‘ 

UppaTECOLors OWin2.0 mWin3.0 mWin3.1 
Purpose Redraws the client area when the application does not have the input focus, but has realized a 

: logical palette. 

Syntax int UpdateColors (HDC ADC) ; 

Description Windows gives preference to the active window when assigning colors from the logical palette. An - 
active window realizing its logical palette may take previously used colors to draw in the client 
area of an inactive window. 

UpdateColors() is provided for rapid updating of colors in windows that do not have the input 
focus. The function is only useful if the application has already realized its logical palette. 

Uses Processing WM_PALETTECHANGED messages (see example below). 

Returns int, not used. 

See Also ' CreatePalette(), SelectPalette(), RealizePalette(), DeleteObject() 

Parameters 

hDC HDC: The device context handle for 
the window. i 

Do lt! Quit 

Related Messages WM_PALETTECHANGED 

Example 


instances of the same program are 
run at the same time. The program 
is set to display a series of narrow 
rectangles, each with a different 
palette color. Figure 12-7 gives a . Figure 12-7. UpdateColors() Example. 

rough idea of the appearance of the 

program's window, when viewing in black and white. Clicking the “Do It!” menu item changes the 
color palette and causes the screen to be redrawn with the new colors. With two or more versions 
running on 2 system that supports 256 colors or less, changing the color palette on one copy of the 


This example is most effective if two 


' program will rob colors from the other. The program handles this by processing 


WM_PALETTECHANGED messages. When a WM_PALETTE-CHANGED message is received, the 
program calls UpdateColors() to make the best use possible of the remaining colors available. 
The program also processes WM_QUERYNEWPALETTE messages. They are received right 
before the application receives the input focus, giving the program a chance to realize the logical 
palette and regain colors lost to other applications when the program was inactive. This example 
shows a standard response to WM_QUERYNEWPALETTE. This is a little redundant, as the pro- 
gram realizes the palette every time a WM_PAINT message is received. The response to 
WM_QUERYNEWPALETTE could be cut down to just doing the WM_PAINT logic. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ; . 


PAINTSTRUCT ps; 

HDC hDC ; 

static HPALETTE hPal ; 

HBRUSH hBrush i 

LOCALHANDLE hLocPal ; 

PLOGPALETTE pLogPal ; 

int i, nNumcol, nNumRes ; 


static 


int = nFreeCol, nColorChange = 0 ; 
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static PALETTEENTRY ~ pepalent £256] ; 


switch (iMessage) /* process windows messages */ 
t 


case WM_CREATE: 


hDC = GetDC (hwnd) , 
nNumCol = GetDeviceCaps (hDC, SIZEPALETTE) ; 
nNumRes = GetDeviceCaps (hDC, NUMRESERVED) ; 


- nFreeCol = nNumCol —- nNumRes ; 


ReleaseDC ChWnd, hDC) ; 


hLocPal = LocalAltoc CLMEM_MOVEABLE, sizeof (LOGPALETTE) *. 
nFreeCol * sizeof (PALETTEENTRY)) ; 

pLogPal = (PLOGPALETTE) LocalLock ChLocPal) ; 

pLogPal->palVersion = 0x300 ; - /* for windows 3.0 */ 

pLogPal->palNumEntries = nFreeCol ; : 

for (i = 0 7 i <nFreeCol ; i++) 


{ 
plogPal—->palPalEntry Cil.peRed = 0; 
‘ pLogPal->palPalEntry Cil.peGreen = 0 ; 
pLogPal->palPalEntry Cid.peBlue = i * (256 J nFreeCol) ; 
_ pLogPal->palPaltEntry Cil.peFlags = 0 ; 
} 


- 


hPal = CreatePalette (pLogPal) ; 
LocalUntock (hLocPal) >; © 
LocalFree ChLocPal) ; ( 
break ; 


case WM_PAINT: 


BeginPaint ChWnd, &ps) ; 

SelectPalette (ps.hdc, hpal, FALSE) ; 

* RealizePalette (ps.hdc) ; 

SelectObject:. Cps.hdc, GetStockObject CWHITE_PEN)) ; 
for (i =0; i <nFreeCol ; i++) 


{ 
hBrush = CreateSolidBrush REAEET SEANQEX C42) ; 
SelectObject (ps. hdc, Paar aie 
Rectangle (ps.hdc, i * 5, 0, Ci "* 5) + 5, 100) ; 
SelectObject (ps.hdc, GetStockObject (BLACK_| BRUSH)? i 
DeleteObject (hBrush) ; 
} 
EndPaint (hWnd, &ps) ; 
break ; es: 
case WM_COMMAND: /* process menu items */ 
switch (wParam) a 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
nColorChanget+ ; 
for (i = 0; i<nFfreeCol ; it+) 
{ ie 
pePalEnt Cil.peRed = i * (256 / nFreeCol) ; 
pePalEnt Cil.peGreen = nColorChange ; 
pePalEnt Cild.peBlue = 
CnColorChange &170: 255) ; 
pePalEnt Cil.peFlags = 0 ; 
} 
' SetPaletteEntries (hPal, 0, nFreeCol, pePalEnt) ; 
InvalidateRect ChWnd, NULL, TRUE) ; 
break ; 
case IDM_QUIT: : /* Rend end of application message x] 
DestroyWindow (hWnd) ; 
break; 
} 
break ; a 
case WM_ QUERYNEWPALETTE: /* about to get focus */ 


hoc = GetDdC ChWnd) ; 
SelectPalette choc, hPal, 0) ; 


~ i _ 
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if (RealizePalette (ChDC)) 
InvalidateRect (hWnd, NULL, TRUE) ; 
ReleaseDC (hWnd, hDC) ; 


break ; 
case WM_PALETTECHANGED: . /* another application changed pal */ 
if (wParam != hWnd) , 
{ es 
hDC = GetDC ChWnd) ; 
SelectPalette (hDC, hPal, 0) ; 
if (RealizePalette (hDC)) 
UpdateColors ChDC) ; 
“ ReleaseDC ChWnd, hDC) ; 
} . 
break ; . 
case WM_DESTROY: /* stop application */ < 


DeleteObject (hPal) 
PostQuitMessage (0) 
break; 

default: & ; 
return DefWindowProc (hWnd, iMessage, wParam, \Param) ; 


Ne Ne 


} ‘ 
return (OL) ; 


Hs 
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Dialog boxes are similar to popup windows. They are frequently used to get input from the user for some specific task, 
such as‘to obtain a file name or to obtain a character string for a search activity. The main difference between dialog 
boxes and popup windows is that the Windows Software Development Kit (SDK) provides a dialog box editor that 
simplifies the task of positioning the buttons and other controls that make up a dialog box. The dialog box editor does 
not provide the program logic to process the messages from the dialog box. That task remains up to the programmer. 

There are functional differences between the behavior of a popup window and a dialog box. Dialog box functions 
use a special default message processing function. This function interprets keystrokes such as the arrow keys, 
and (SHIFT)-(7A8) to allow selection of controls in the dialog box using the keyboard. Any activity that can be performed 
in a dialog box can also be performed in a child or popup window. Dialog boxes are more convenient for simple popup 
windows that make use of normal control items like buttons and list boxes. Popup and child windows are better if you 
will be doing extensive painting on the window, or will be modifying the standard behavior of the window. 


An Example Dialog Box WO Example Dialog Box 34.0) 2 de 
To get started, let’s modify the GENERIC application we created in Chap- 
ter 1 to show a dialog box window. The dialog box will appear as shown in 
Figure 13-1. It is similar to the dialog box style used by most programs for This dialog box does noti.ing. 
an “About Box,” although this one has two pushbuttons to illustrate how — 
control messages are processed. OK 
The first step is to run the SDK Dialog Box Editor application to cre- 
ate the rough dialog box template. The DBEditor will generate two files, Figure 13-1. A Dialog Box. 
a dialog box template file and a header file. It is best to use a separate - . 
header file to store the ID values for the dialog box controls. The DBEditor will allow you to update and add to this file 
for new controls and new dialog boxes as they are added to the application. The DBEditor generates a dialog box 
template file like the one shown in Listing 13-1. Most people give their dialog box template files the extension “.DLG.” 
In this case, the dialog box is given the name “EXAMPLEDIALOG.” We will discuss the meaning of all of the items in 
the dialog box definition later in this chapter. 


generic Example 


oe Listing 13-1. GENERIC.DLG The Dialog Box Tempiate File Created with the DBEditor 


EXAMPLEDIALOG DIALOG LOADONCALL MOVEABLE DISCARDABLE 20, 34, 160, 67 
CAPTION “Example Dialog Box" 
FONT 10, “Helv” ; 
STYLE WS_. BORDER | WS_CAPTION | WS_DLGFRAME [| DS_MODALFRAME | WS_POPUP 
BEGIN 
CONTROL “generic Example", -1, "static", 
SS_CENTER | WS_ GROUP | WS CHILD, 42, 12, 81, 10 
CONTROL "This dialog box does nothing.", -1, "static", 
SS_CENTER | WS_GROUP | WS CHILD, 28, 30, 115, 10 
CONTROL “generic”, -1, "static", 
SS_ICON | WS_CHILD, 10, 10, 0, 0 
CONTROL "OK", DLI_OK, “button", 
BS_DEFPUSHBUTTON | WS_TABSTOP | WS_CHILD, 30, 50, 40, 14 
CONTROL “Not OK", DLI_NOTOK, "button", 
BS_PUSHBUTTON | WS_TABSTOP | WS_CHILD, 100, 50, 40, 14 
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CONTROL “generic”, -1, "static", 
SS_ICON | WS_CHILD, 5, 13, 16, 16 

END 

The dialog box template file is a normal ASCII file and can be edited. With the Windows 2.0 version of the 
DBEditor, it was frequently necessary to go in and edit the dialog box template to add captions, change fonts, etc. 
These features have all been added to the Windows 3.0 version of the DBEditor, so there is seldom a reason to manu- 
ally change values. The header file that contains the ID values for all of the controls in every dialog box the application 
uses can be maintained completely from within the DBEditor. For the simple example shown in Listing 13-2, there are 
only the two pushbutton controls that need ID values. All of the static items, such as the text strings and the icon, are 
given ID values of —1. These items are never selected. 


© Listing 13-2. GENERICD.H. The Dialog Box ID Header File 


define DLI_OK 101 
#define DLI_NOTOK 102 


It is best to use a numbering convention to keep menu item IDs, dialog box control IDs, and child window control 
IDs separate. A good system is to number menu items between | and 99, dialog box IDs between 100 and 999, and child 
window control IDs above 1000. The DBEditor will create ID values starting at 100 by default, so this is convenient. 

The dialog box template must be compiled to make a binary resource file (.RES) by the resource compiler 
(RC.EXE) to make the data useful to the application program. The dialog box template file can be either separately 
compiled or included in the program’s resource oe as shown in Listing 13-3. Don’t forget to include the header file 
containing the dialog box ID values. 


© Listing 13-3. GENERIC.RC The Resource Script File 


/* generic.re */ 


#include <windows.h> 
#include “generic.h" 
#include “genericd.h" 
#include “generic.dlg" 


2 


generic ICON generic.ico j 
generic MENU 
BEGIN 
MENUITEM "&Do Ic!" IDM_DOIT 
MENUITEM “SQuit", IDM_QUIT 
END : 


Note that the resource scripi file includes the ICON statement. The “generic” icon is also used in the dialog box. 
Windows does not provide an automated way to process messages from the controls in a dialog box. You will have to 
create a message processing function for every dialog box in the program. These functions are called “Dialog Box 
Functions.” They are similar to the separate message processing functions we explored in Chapter 3, Windows Sup- 
port Functions, for child and popup windows. Listing 13-4 is a typical example, which processes messages for the 
simple dialog box previously defined. 


© Listing 13-4. A Dialog Box Function 
BOOL FAR PASCAL DialogProc (CHWND hDlg, WORD wMess, WORD wParam, LONG LParam) 
{ 


switch (CwMess) 


case WM_INITDIALOG: ; 

/* initialization functions go here */ 
return TRUE ; s 

case WM_COMMAND: /* One of the controls was activated */ 
switch (wParam) 
{ 


case DLI_OK: 
EndDialog ChDlg, 0) ; 
return TRUE ; 

case DLI_NOTOK: 
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' MessageBeep (> ; 
: return TRUE ; 
A ae 
return TRUE ; 
- case WM_DESTROY: 
; EndDialog -ChDlg, 0) ; 
return TRUE ; 
} 4 
return FALSE ; 


In this case, the dialog box quits if the user clicks the “OK” button, and just beeps if the “Not OK” button is clicked. 
Although the dialog box function looks a lot like a child window message processing function, there are differences. 


1. Windows sends a WM_INITDIALOG message to the function before the dialog box is made visible. This message 
replaces the WM_CREATE message that is sent to child windows. 


2. Dialog box functions do not pass messages on to DefWindowProc(). Instead, Windows automatically passes mes- 
sages to a special default message processing logic used only for the dialog boxes. Normally, this is done automati- 
cally, so you will not reference the DefDlgProc() function at the bottom of the dialog box function. The only 

_ exception is a special case where the dialog box has its own window class. See the DefDigProc() function descrip- 
tion for an example. 


3. Dialog box functions should return TRUE if the message was processed within the function, and return FALSE if 
- the message was not processed. 


4, Dialog box functions end the dialog box’s existence by saline EndDialog(). 


The dialog box function must be included i in the EXPORTS section of the program’s .DEF definition file, as shown 
in Listing 18-5. 


> Listing 13-5. GENERIC.DEF Definition File 


NAME SENERTE 

DESCRIPTION "generic windows program! 
EXETYPE WINDOWS 

STUB "WINSTUB.EXE' . 

CODE PRELOAD MOVEABLE 

DATA PRELOAD MOVEABLE MULTIPLE 
HEAPSIZE 1024 ‘ 
-STACKSIZE 4096 


EXPORTS unerres 
DialogProc 


._ The dialog box function prototype, as er in Listing 13- 6, must also pe included in the program’ S hades file for 
the source code to compile properly. 


> Listing 13-6. GENERIC.H Header File 
/* generic.h */ 
#define iDM_DOIT 1 /* menu item id values */ 
Hdefine IDM_QUIT 2 
/* global variables */ 
int ghInstance ; 
char gszAppName [CJ = “generic"™ ; 
/* function prototypes */ 
Long FAR PASCAL WndProc CHWND, unsigned, WORD, ONG? 3 
BOOL FAR PASCAL DialogProc CHWND, WORD, WORD, LONG) ; 


~ 


Finally we get to the point that we can actually call the dialog box from within the program. Listing 13. 7 shows a 
_ typical calling sequence. 


© Listing 13-7. GENERIC.C Reverct 
Long rae PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


FARPROC LpfnDLgProc ; 
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switch (CiMessage) ae /* process windows messages */ 
{ . 
case WM_COMMAND: fo /* process menu items */ 
“switch (wParam) 
case IDM_DOIT: /* run dialog box */ 
LpfnDlgProc = MakeProcInstance (DialogProc, ghInstance) ; 
DialogBox (ghInstance, “ExampleDialog", hWnd, 
lpfnDlgProc) ; 
freer roctussance CLpfnDlgProe) ; 
break ; 
[Other program lines] 


The DialogBox() function creates and runs the dialog box. DialogBox() requires the procedure-instance address 
of the dialog box function. MakeProcInstance() is used to obtain this value, and FreeProcInstance() is used to release 
it from memory. This probably looks like a lot of work for so simple a task. The saving grace is that, like WndProc() 
functions, dialog box functions all tend to be similar. Once you have created one, all of the rest are a matter of 
modification. The DBEditor is a big help in taking the guesswork out of creating nice looking dialog boxes. 


Types of Dialog Boxes. 


The most common type of dialog box is a “modal dialog box.” When a modal dialog boxi is on the screen, the user cannot 
switch to another part of the program. By default, they limit access to the other visible windows of the program that 
~~ ealled the dialog box. The user can still switch to other programs while the modal dialog box is displayed. 

You can make a system modal dialog box by specifying the WS_SYSMODAL style in the dialog box template. 
_- System modal dialog boxes can also be created by calling the SetSysModalWindow() function. System modal dialog 
boxes take over the whole screen. They are only appropriate if there is a serious problem that the user cannot ignore, 
such as having the system run out of memory. 

Modal dialog boxes and system modal dialog boxes are created with the DialogBox() function. (Actually, there are 
several versions of DialogBox() that we will discuss in a moment.) When you use DialogBox(), all of the window's 
messages are sent to the dialog box function while the dialog box is on the screen. The rest of the program just sits 
there until EndDialog() is called from within the dialog box function to close the dialog box. 

. Less common, but sometimes handy, are “modeless” dialog boxes. They are basically popup windows. Modeless 

_ dialog boxes hang around on the screen, and they can obtain and Jose the input focus. They are frequently used for 
small windows containing lists of tools, or for popup windows that display a continually updated set of values like the 
cursor X,Y position. Modeless dialog boxes are created with CreateDialog(). Again, there are several versions of 
CreateDialog(), but they all accomplish the same basic task of displaying and initializing a modeless dialog box. 
Because the modeless dialog box remains on the screen, it must share messages with the application’s WndProc() 
function. This requires a modification to the program’s message loop if the modeless dialog box is to respond to 
keyboard selections using the and arrow keys. A typical message loop for an application containing one or more 
modeless dialog boxes is as follows: 


while (GetMessage (&msg, NULL, 0, 0)) /* the message Loop */ 

{ . sae 
if (hDlgModeless == NULL {| !IsDialogMessage (hDlgModeless, &msg)) 
t ai . ; 


TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
hDigModeless is a HWND handle for the dialog box. This global variable is set to NULL if the modeless dialog box 
is not displayed, and set to the dialog box handle if the modeless dialog box is currently on the screen. 
The IsDialogMessage() function determines if a message from Windows is meant for the dialog box. If so, the 
message is sent to the dialog box function and should not be processed by the normal TranslateMessage() and 
DispesceMleseeel) functions. 
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Indirect and Parameter Dialog Box Ranedoaus : 

DialogBox() and CreateDialog() are the basic functions for creating modal and modeless dialog boxes, respectively. 
There are actually five versions of each of these functions. I’ll use the modal dialog box functions as an example, but - 
the same comments apply to the modeless dialog box functions related to CreateDialog(). As previously mentioned, 

the dialog box template file is compiled using the resource compiler to make a binary .RES resource file. The compiled 

resource information is linked into the program when RC.EXE is called a second time at the end of the compile/ink 

cycle. When you call DialogBox(), the resource data is loaded into memory and executed. This is how Windows knows 

how to display the dialog box image. When the dialog box is closed (EndDialog() i is called to do this), the resource data 

is released. Sometimes it is desirable to control when the dialog box template data is loaded or unloaded from memory. 

To do this, load and lock the resource data for the dialog box in advance, and then call DialogBoxIndirect(). 

DialogBoxIndirect() takes a handle to the locked resource data in memory and runs the dialog box. The dialog box 

resource data is not removed from memory when the dialog box exits. Do this manually by using UnlockResource() 

and FreeResource(). Examples of using these functions are included with the DialogBoxIndirect() function descrip- 

tion. More detail is included in Chapter 25, Resources. 

Indirect loading of dialog box template data also makes it possible to modify the dialog box definition as the 
application runs. (This subject is discussed later in this chapter under the heading Dynamic Dialog Boxes.) _ 

The DialogBox() function has another limitation. There is no clean way to pass dialog box information, such as 
variable names and constants. Prior to Windows 3.0, programmers were forced to pass data by using global variables. 
This is not a good practice, as it makes the dialog box functions less portable. With Windows 3.0, several new functions 
have been added that include data passing between the calling function and the dialog box function. These are the 
“Param” versions of DialogBox() and CreateDialog(). DialogBoxParam() is a typical example. This function allows a 
32-bit value to be passed to the dialog box function. Normally, 32 bits is not enough room to pass all of the data the 
dialog box function will need. In this case, the 32-bit value can be used to pass a handle to a memory area that contains 
the data. The memory block is allocated outside of the dialog box function. The dialog box function uses the handle to 
lock the memory area, read and change values, and then unlock the memory block. See the ae under pea 
BoxParam() for a typical application. en — 


Communicating with Dialog Box Controls 
The controls within a dialog box, such as buttons, list boxes, and static text, are. 
all child windows, The dialog box receives WM_COMMAND messages from the 


A * : ical list bux 
controls when they are activated, and it can send messages to the controls using Ee ae SEEBEG in’ dialog bor 
SendMessage(). Usually, it is easier to use the specialized SendDlgitemMess- Third String 


age() function from within a dialog box, as it uses the conigols ID value rather | a 
than the control’s window handle. 

To see how messages are handled from within a dialog box function, we will Figure 13-2. A List Box Control 
use a list box control. List boxes are child window controls that allow the userto ina Dialog Boz. 
select an item from among a number of choices. Although list box controls can 
be attached to any window or child window, they are most often part of dialog boxes. Common uses are to select a file 
from a group of files in a subdirectory, to select a tool from a list of tools, etc. 

The Windows SDK does not provide a series of specialized functions to deal with list boxes. Instead, the applica- 
tion communicates with the list box with a series of Windows messages. The list box communicates with the applica- 
tion by sending WM_COMMAND messages, with the specific message encoded in the wParam and lParam 
parameters. The messages are described in Chapter 9, Windows Messages. To see how this works in a dialog box, 
consider the simple example shown in Figure 13-2. The dialog box contains one list box, which contains four character _ 
strings. The user selects one of the items using the mouse, and then clicks the “OK” button. The selected value is then 
displayed on the application’s client area. | 

The dialog box was defined using the 2vk DBEditor application. The resulting oe box template file i is as 
follows: 
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> Listing 13-8. Dialog Box Definition Containing a List Box 


EXAMPLEDIALOG DIALOG LOADONCALL MOVEABLE DISCARDABLE 20, 36, 162, 75 
CAPTION “Example Dialog Box" 
FONT 10, “Helv" 
STYLE WS_BORDER [{ WS_CAPTION | WS_DLGFRAME | DS_MODALFRAME | WS_POPUP 
BEGIN 
CONTROL "OK", DLI_OK, "button", 
BS _DEFPUSHBUTTON { WS_TABSTOP } ws CHILD, 102, 48, 40, 14 
CONTROL “", DLI_LISTBOX, "“Listbox", 
LBS_NOTIFY | LBS_SORT } LBS_STANDARD | LBS_HASSTRINGS 
| WS_BORDER { WS_VSCROLL | WS_CHILD, 6, 15, 87, 49 
CONTROL “Typical List box in a dialog box.", -1, “static”, 
SS_LEFT { WS_CHILD, 102, 15, 54, 27 
END : 
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The list box control definition contains several flags. The key ones are LBS_SORT, which causes the items to be 
sorted in ASCH] sequence, and LBS_HASSTRINGS, which tells the list box control to store thelist box items in its own 
memory area. The LBS_NOTIFY style is also critical, as without it the list box will not send WM _COMMAND messages 


to the application when the user clicks or double-clicks an item. 


The processing logic for the dialog box function is fairly simple. The list box items are aaaed to the list box when 
the dialog box is first created. Once the dialog box is displayed, clicking an item in the list box results in a 
WM_COMMAND message being sent to the dialog box function. The dialog box function logic extracts the current 
selection number and the string that selection contains, and stores the values in the global variables nSelection and 


cSelection. 


o> Listing 13-9. Dialog Box Procedure for the List Box Example 


BOOL FAR PASCAL DialogProc CHWND hDlg, WORD wMess, WORD wParam, LONG lParam) 


{ 
switch (wMess) 


case WM_INITDIALOG: 


SendDlgItemMessage ChDlg, DLI_LISTBOX, WM_SETREDRAW, 


FALSE, OL) ; 


SéndDigitemMessage “ChDtg, DLI_LISTBOX, LB_ ADDSTRING, O,. 


CDWORD)CLPSTR) "First String") ; 


SendblgltemMessage (hDlg, DLI —LISTBOX, LB _ADDSTRING, 0, 


CDWORD)CLPSTR) “Second String") ; 


SendDigItemMessage (hDlg, DLI_LISTBOX, LB_ADDSTRING, 0, 


CDWORD)CLPSTR) "Third String") ; 


SendDligltemMessage (hDlg, DLI_LISTBOX, LBADDSTRING, 0, 


CDWORD)CLPSTR) “Fourth String”) ; 


SendDlgItemMessage (hDlg, PER HES Boke MASSE TRED RIM: 


nSelection = SendDlgItem Message (hDlg, 
DLI_LISTBOX, LB_GETCURSEL, 0, OL) ; 

SendDlgltemMessage (hDlg, DLI_LISTBOX, 
LB_GETTEXT, nSelection, 
CLONG)CLPSTR) cSelection) ; 


TRUE, OL) ; 
return TRUE ; \ 
case WM_COMMAND: /*® One of the controls was activated */ 
TS switch (wParam) ; 
{ 
case DLI_OK: 
EndDialog ChDlg, 0) 
return TRUE ; 
case DLI_LISTBOX: 
if CHIWORD (tpardm) == LBN_SELCHANGE) 
{ 
} 
} ; 


return TRUE ; 
case WM_DESTROY: 
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EndDialog (hDlg, 0) ; 
return TRUE ; 
} ; 
return FALSE ; 


_ Review Chapter 9, Windows Messages, for the full list of messages concerning dialog boxes and combo boxes. 
There are other examples in those sections, including creating list boxes with the owner-redrawn style. .Owner- 
redrawn list boxes and combo boxes allow selection from groups of ee ia etc. Windows includes direct 

- support for filling a list with a selected group of file names. 


- The Dialog Box Keyboard Interface 


The built-in logic Windows provides for dialog boxes includes provisions for a keyboard alternative to selecting items 
with the mouse. Three sets of keyboard logic can be provided: keyboard “hot keys” for selecting items using (tr)-letter 
key combinations; response to the (as) key for big movements; and response to the keyboard arrow keys for smaller 
movements. 

The (acrHetter key selection logic i is done the same way for dialog boxes as for menu items. If you fneeeiis’ aletter 
in the control's text string with an ampersand (&), the letter following the & is underlined. The & characters are not 
displayed. For example, the following definition for a DEFPUSHBUTTON control would use (t)-o for a hot key to — 
activate the “Done” button. . 


CONTROL "@Done", DLI_DONE, "button", — 
BS_DEFPUSHBUTTON ‘ WS_TABSTOP | WS_CHILD, 45, 66, 48, 12 


Using the (a8) and arrow keys is sometimes a convenient alternative to the mouse, and critical it users who are 
not using a mouse. To take advantage of this logic, you set certain elements i in the dialog box template with the 
WS_TABSTOP and/or WS_GROUP style. Here is an example 
EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE 10, 18, 145, 80— 

STYLE WS_DLGFRAME | WS_VISIBLE | WS_POPUP 
BEGIN 
CONTROL "", DLI_CHECK1, “button", 7 
BS_CHECKBOX | WS_TABSTOP | WS_GROUP | ws CHILD, 12, 20, 48, 12 
CONTROL “", DLI_CHECK2, "button", 
BS_CHECKBOX | WS_CHILD, 12, 39, 48, 12 

CONTROL "", DLI_CHECK3, “button”, 

BS_CHECKBOX | WS_TABSTOP | WS__ GROUP | WS_CHILD, 84, 21, 45, 12 

CONTROL “", DLI_CHECK4, "button", 

BS_CHECKBOX | WS_CHILD, 84, 39, 45, 12 
CONTROL “Done”, DLI_DONE, "button", 


BS __DEFPUSHBUTTON ' | WS_TABSTOP | WS_CHILD, 45, 66, 48, 12 © 
END 


~The WS_TABSTOP style marks each item that will receive the input focus when the user presses (ta8) Or (HFT) GE? 
(vas). In this case, three items have this style. The WS | GROUP stylémarks the beginning of a group. All of the items up 
until the next WS_GROUP item are part of the sarhe group. The user can use the arrow keys0.move betaveen items in 
a group, but not outside of the group. The key will select or deselect a pushbutton, check box, or radio button 
item that has the input focus. This procedure has the same effect as selection with the left mouse button. 

The default keyboard interface works fine if your dialog box template is in a logical order. You will probably find 
that this is not the case when you first create the dialog box template using the DBEditor. Go in with a text editor and . 
edit the template as soon as it is done, moving the items until they are in the right order for the WS_! TABSTOP and 
WS GROUP style markers to work properly. The order of the lines in the dialog box template also: determines the. 
order in which the items are displayed on the screen as the dialog box is painted. Having the screen painted i ina 

_ reasonable order is more aesthetic than having the me appear randomly over the screen. 


Dynamic Dialog Boxes | 
Some applications require that the dialog box be altered as the program operates. For example, a database applica- 
tion would need to add and subtract fields from a data-entry dialog box to match the structure of the underlying 
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- database. This is a complex subject, so you may wish to skip to the next section if you do not need this information 
right away. For simple changes, the child window controls in the dialog box can be manipulated directly. For example, 
MoveWindow() can be called to relocate a control. For complete control over a dialog box during run time, the appli- 
cation can modify the dialog box definition in memory. This is not a simple matter, as the definition of a dialog box 
contains three separate data structures, each with variable length fields. 

The CreateDialogIndirect(), CreateDialogIndirectParam(), DialogBoxIndirect(), and DialogBoxIndirectParam() 
functions read the data in memory in a specified format and create a dialog box. The simplest way to create data in the. 
right format is to define the dialog box with the DBEditor, add it to the application’s resources, and load it into 
memory with LoadResource() and LockResource(). The data will be in the format defined below. You will have to 
create the data format from scratch in an allocated memory block if your dialog box is to be truly “dynamic." 

The overall structure of a dialog box definition in memory is as follows: 


DLGTEMPLATE The header information for the dialog box. 
FONTINFO The data structure for the font data. 
DLGITEMTEMPLATE. ‘The data structure for each control in the dialog box. 


These data structures are placed one after the other i in memory. The data structures are not defined in 
WINDOWS.H. Here are their definitions: 


& Listing 13-10. Dialog Box Data Structures © 


typedef struct {¢ /* only one of these structs per dial. box */ 
long dtStyle ; _- ¢* Any of the DS_ styles (CreateWindow()) */ 
BYTE dtItemCount ; /* number of controls, 255 max */ 
int dtX ; ; /* X pos. of-upper Left cf the dialog box */ 
int © dtyY ' /* Y pos. of upper Left of the dialog box */ 
int dtcCx ; /* width of the dialog box */ 
int dtcy ; /* height of the dialog box */ 
char dtMenuName £1] ; /* menu name, null term. string, NULL=none */ 
char dtClassName £1] ; /* class, null term. string, NULL=standard */ 
char dtCaptionText £1] ; /* dialog box caption, nutl term. string-*/ 

} DLGTEMPLATE ; 

typedef struct ¢ 7* only one ef these striics per dial. box */ 

short int PointSize ; /* point size of font */ 

char - szTypeface £1] ; /* typeface name, null term. string */ 


} FONTINFO ; 


typedef struct ¢ t 5 /* one of these for each control */ 
int dtilX ; /* X pos. of upper left of the control */ 
int _ dtily ; /* Y pos. of upper left of the control */ 
int dtilCX ; /* width of the control */ 
int dtilCy ; ' /*® Y pos. of upper left of the control */ 
int dtilIp ; _ /* control id value */ 
long ~dtilStyle ; /* control child window syle */ 
char dtilCtass [1] ; /* null term. string "BUTTON", "EDIT", etc. */ 
char dtilText [1] ; /* control text, null term. string */ 
BYTE dtilinfo ; /* number of bytes of data that follow */ 
PTR dtilData ; /* the extra data bytes go here */ 


} DLGITEMTEMPLATE ; 


The size and location of the dialog box and all controls are given in dialog box base units. These are relative to the 
size of the font in use. Vertical dimensions are in eighths of the font height, and horizontal dimensions are in fourths 
of the font width. 

All of the character elements in the structures are variable-length arrays. The minimum size will be one byte, for 
a NULL character. Normally, there will be a series of ASCII characters, followed by a terminating NULL. Windows 
parses the memory block, using the terminating NULL character to mark the end of the field. 

A full demonstration of the use of dynamic dialog boxes is beyond the scope of this book. If you are interested in — 
- more information, refer to Chapter 3 of Jeffrey Richter’s excellent book Windows 3: A Developer's Guide (1991, M&T 
Books) for a complete example: 
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. Dialog Template Statement Description 


This section contains a full list of the statements that you can include in the dialog box jaanplate: Notinally. you will 
use the SDK DBEditor to do all of the additions and changes to the dialog box template file. Sometimes it is easier to 
just go in and edit a specific value in the resource script file for small changes. One of the peculiarities of dialog box 
templates is the system of units. Instead of measuring locations in terms of pixels, or logical units, dialog boxes use 
“dialog base units.” These units are fractions of the dialog box character font, size. The horizontal direction is mea- 
sured in fourths of a character width, and the vertical direction is measured in eighths of a character height. The 
effect of this system of units is to properly scale the dialog box, regardless of the screen resolution in use. Typically 

_ high-resolution monitors will use more pixels per character, so the character size remains about the same as on a low- 
resolution monitor. A side effect of this system is that you can change the size of a dialog box by simply picking a 
different font. The FONT statement is provided for this purpose. . 


DIALOG | BWin2.0 mWin3.0 mWin3.1 
Purpose Starts the dialog box template definition. 
Syntax .  —— namelD DIALOG [load-option]|mem-option] x,y, width, height, (spesanarntenieaa| 
Example EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE 10, 18, 145, 80 
BEGIN 
adialve! box items defined here) 
END 
Description This statement starts the dialog box template definition. All statenients from BEGIN until the 


END statement is reached are part of the dialog box template. 
- ThexamelD string is the name of the dialog box. This is the character string that is used with 
DialogBox() to specify which dialog box should be loaded and executed. 

The load-option can be either PRELOAD or LOADONCALL. PRELOAD specifies that the 
dialog box resource data be loaded when the application starts. Doing so takes up memory, but 
makes the dialog box appear quickly. LOADONCALL is the normal (default) option, where the 
dialog box resource data is not loaded into memory until needed. 

The mem- option is a combination of FIXED, MOVEABLE, and DISCARDABLE. Normally, 
both the MOVEABLE and DISCARDABLE styles are chosen. FIXED should be avoided, as this 
freezes the dialog box resource data in memory, making it much more difficult for Windows to 
optimize memory use. 

xy, width, height specifies the position and size of the dialog box. Dialog base units are used 
for all dimensions. They location is relative to the upper left corner of the window which called 
the dialog box. 

The option-statements include STYLE, CAPTION, MENU, CLASS, and FONT. All-statements 
after DIALOG, up to the BEGIN statement in the dialog box definition, are assumed to be option 


statements. 
STYLE | mWin20 mWin3.0 mWin3.1 
Purpose | Specifies the window aie to use for the dialog we 
Syntax STYLE style 
Example STYLE WS_DLGFRAME | WS_’ VISIBLE | WS_POPUP 
Description All of the styles described in Chapter 2, Creating Windows, under CreateWindow() that start 


with WS_ or DS_ can be used in the dialog box style. If you are creating a modeless dialog box 

with CreateDialog(), be sure to include the WS_VISIBLE style in order to avoid using Show- 

Window() to make the dialog box visible. Dialog boxes cannot use the WM_ MINIMIZEBOX and 
- WM_MAXIMIZEBOX styles. 
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N : 

CAPTION mWin2.0 wWin30 mWin3.1 

Purpose Specifies the text used in the dialog box caption bar. 

Syntax ~ CAPTION capliontext 

Example CAPTION “Dialog Box Title. Here” 

Description Used with dialog boxes that have the WS_CAPTION style. This is a good idea, as it allows the user 

_ to move the dialog box on the screen. The caption is also a visual reminder of what activity is 

taking place. 

CLASS : | mWin2.0  mWin3.0 mWin3.l 

Purpose ' Specifies that the dialog box is to have its own window class. 

Syntax CLASS classname 

Example _ CLASS “separate” 

Description _—Normally, a dialog box shares the window class of the parent. This statement causes a separate 
class to be used for the dialog box. The class must be registered in advance with RegisterClass(). 
The class must be registered with the cblWndExtra element set to DLGWINDOWEXTRA. Dialog 
box functions for windows with their own class must specify a separate default message process- 
ing function. See the example under DefD1gProc() to see how this is done. 

FONT mWin2.0 mWin3.0 mWin3.1 

Purpose Specifies the font to use inside the dialog box for all controls. . 

Syntax FONT pointsize, typeface 

Example _ FONT 10, “Helv” . 

Description As previously mentioned, the font determines not only the typeface, but also the sizing of every 


control and the dialog box itself. This is because dialog box dimensions use dialog base units, 
computed as fractions of the font character size. The 10-point “Helv” font is a good choice for 
most dialog boxes, as it matches the font used in the dialog boxes of the applications supplied 
with Windows 3.0. . 


Dialog Box Control Statements 


Windows provides two equivalent ways to specify a child window control in a dialog box template. One way is to use an 
explicit statement like COMBOBOX. The other way is to use the CONTROL statement, which will then include the 
“combobox” style as a parameter. The DBEditor always uses the CONTROL statement. The explicit statements are 
leftovers from the days before the DBEditor was available, when programmers coded dialog boxes by hand. As an 


example, the following two examples produce the same control. 


CONTROL “Push Me", DLI_BUTTON1, “button", 
BS_DEFPUSHBUTTON | WS_TABSTOP | WS_CHILD, 45, 66, 48, 12 


DEFPUSHBUTTON "Push Me", DLI_BUTTON1, 45, 66, 48, 12, WS_TABSTOP 


A number of the statements include the position and size of the control. In the descriptions that follow, they. will 
be labeled “x, y, width, height.” Keep in mind that all values are integers, and all use dialog base units. 

The ID values for each control are normally defined in a separate header file. By convention, dialog box control | 
~ items are normally given names starting with “DLI_” for “DiaLog Item.” For the controls with the optional style _ 
parameter, the choices include the WS_TABSTOP and/or WS_GROUP styles. These control the default keyboard in- 
terface, as described above. The two styles can be combined with the C language binary OR operator (1). 


561 


WINDOWS API BIBLE 


CHECKBOX 2 ae mWin2.0 gWin3.0 mWin3.1 
Purpose Defines a check box control.’ 
Syntax CHECKBOX tert, id, x, y, width, height [style] ° 

Example : CHECKBOX “Autosave On/Off”, DLI_CHECKBOX, 3, 10, 35, 15 

Description Check boxes belong to the “button” window class. They are ideal for specifying binary choices, 
: _' such as if an autosave feature is on or off. ; ss 
COMBOBOX mWin2.0 m@Win3.0 mWin3.1 
Purpose Defines a combo box control. 

Syntax — _ COMBOBOX id, a, y, width, height, [style] 

Example . COMBOBOX DLI_COMBO, 40, 10, 60, 90, WS_VSCROLL 

Description Combo boxes are a new addition with Windows 3.0. They include an edit control at the top, com- 


bined with a drop-down list box at the bottom for making a selection. The optional style param- 
eter can include any combination of WS_TABSTOP, WS_GROUP, WS_DISABLED, and 
WS_VSCROLL. Examples using combo boxes are included in Chapter 9, Windows Messages, in 
the combo box message section. 


CONTROL mWin2.0 mWin3.0 m8 Win3.1 


Purpose Specifies all forms of child window control within a dialog box. 

Syntax CONTROL text, id, class, style, x, y, width, height 

Example =~ CONTROL “Push Me”, DLI_BUTTON1, “button”, BS_DEFPUSHBUTTON | WS_TABSTOP | 
WS_CHILD, 45, 66, 48, 12 


Description This is the general-purpose statement for dpceitving all types of controls used in dialog box tem- 
‘ plates. The DBEditor uses this form when it creates a template file. The deat field specifies the 
character string that will appear in the control. This is not always displayed. For example, list box 
controls do not display a string until the string is added to the body of the list box using the 
LB_ADDTEXT message. 
The class parameter can be either BUTTON, COMBOBOX, EDIT, LISTBOX, SCROLLBAR, or 
STATIC. See the descriptions in Chapter 2, Table 2-2 under CreateWindow() for the full details. 
The child window style is also identical to the styles used in CreateWindow(). Table 2-3 contains 
a complete list of these values. 


CTEXT | oe. mWin2.0. mWin3.0  mWin3.1 
Purpose Defines a centered static text control. 

Syntax CTEXT text, id, x, y, width, height, [style] 

Example CTEXT “Centered Text,” —1, 10, 10, 100, 15 . 

Description This control places static text in a dialog box. The text is centered within the bounds of the 


rectangle specified by x, y, width, height. Normally, static text controls are given an ID value of 
—1, as they are never selected. An exception is where the dialog box function Chale the text 
content as the dialog box operates. 


DEFPUSHBUTTON 3 Win 2.0 mWin3.0° mWin3.1 


Purpose: . Defines the default pushbutton for a dialog box. 
Syntax DEFPUSHBUTTON teat, id, x, y, width, height, style] 
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Example 
Description | 


EDITTEXT 


Purpose 
Syntax 
Example 
Description 


GROUPBOX 


Purpose 
Syntax 
Example 
Description 


ICON 


Purpose 
Syntax 
Description 
Example 


LISTBOX 


Purpose 
Syntax 
Example 
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DEFPUSHBUTTON “Cancel”, DLI_CANCEL, 40, 10, 40, 15, WS_TABSTOP 


The default pushbutton is the button that will be activated if the user presses when the 
dialog box first starts operation. There can be only one DEFPUSHBUTTON control in a dialog box 
definition. It will be displayed on the screen with a bold border. The other buttons should have 
the PUSHBUTTON style. ; 


BWin2.0 wmWin3.0 wm Win3.l 


Defines an editable text control in a dialog box. 
EDITTEXT id, 2, y, width, height, [style] 
EDITTEXT DLI_EDIT, 10, 20, 45, 15, WS_HSCROLL . 


Edit controls are the standard method for getting user input for typed text or numbers. Windows 
includes a lot of built-in logic in edit controls, including selection of groups of characters by 
clicking and dragging the mouse cursor, deletion and insertion of characters, cursor (arrow) key 
support, etc. Edit controls can be one line of text, or multiple lines, including both horizontal and 
vertical scrolling of the client area of the edit control. Chapter 9, Windows Messages, includes an 
example of a multiline edit control in the section on Edit Control Messages. 

‘The style parameter can include any combination of the following styles: WS_TABSTOP, 
WS_GROUP, WS_VSCROLL (vertical scroll bar); WS_HSCROLL (horizontal scroll bar), 
WS_BORDER, and WS_DISABLED. Text is aligned based on ES_LEFT, ES_RIGHT, or 
ES_CENTER. See Table 2-3 for additional details on edit styles. 


BWin2.0 mWin3.0 
Draws a rectangle with a title at the top left around a group of other controls. 
GROUPBOX text, id, x, y, width, height, [style] 
GROUPBOX “Filetype Choices:”, —1, 10, 10, 65, 100 ae 


Check boxes or radio buttons frequently deal with related options, or choices from a narrow set of 
possibilities. Surrounding the related options with a group box makes it clear that the controls 
belong to related functions. The WS_TABSTOP and WS_GROUP styles can be applied to the group 
control, but normally it is better to have the first item within the group receive the input focus. 


@ Win 3.1 


m@Win2.0 mWin3.0 wmWin3.) 
Places an icon within a dialog box. 

ICON text, id, x, y, [style] 

ICON “generic”, DLI_ICON, 40, 40 


Icons belong to the “static” class of controls. The éeat parameter is the name of the icon, specified 
elsewhere in the program’s resource .RC file with an ICON statement such as 


generic ICON generic.ico 


The x,y parameters specify the upper left corner of the icon in dialog units. The size of the icon is 


fixed, so there are no height or width parameters. The only allowed style is SS_ICON. 


mw Win2.0) «om Win3.0) =m Win3.l 
Defines a list box control within a dialog box. " 
LISTBOX id, 2; y, width, height, [style] 
LISTBOX DLI_LIST, 10, 10,50, 100, LBS_NOTIFY, WS_VSCROLL, WS_BORDER 
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RTEXT “Right Justified Text”, ~1, 10, 10, 150, 15 : te 


List box controls are the most common. means of allowing users to select an item from a list of 


Description 
possibilities. More than one selection is possible if the list box includes the LBS_MULTIPLESEL 
‘style. The complete list of style possibilities is given in Table 2-3 under the CreateWindow() func- 
- tion description. An example program with a list box control is included at the beginning of this - 
chapter. Additional examples are given in Chapter 8, Message Processing Functions, in the list 
box messages section. 
LTEXT > mWin2.0 m8 Win3.0 - mWin3.1 
Purpose Defines a left-justified static text control. 
Syntax LTEXT text, id, x, y, width, height, [style] 
Example LTEXT “Left Justified Text”, -1, 10,10, 150,15 | 
Description This control places static text in a dialog box. The text is justified to the left border within the 
bounds of the rectangle specified by 2, y, width, height. Normally, static text controls are given 
an ID value of -1 because they are never selected. An exception is when the dialog box function 
changes the text content as the dialog box operates. 
MENU mWin2.0 wWin3d.0 mWin31 
Purpose — Specifies a menu to be attached to the dialog box. 
. Syntax MENU menuname 
Example MENU testmenu 
Description Used with dialog boxes that have menus. This is unusual, but possible. The menu uraust be defined 
ene en as in the proerann: s .RC resource script file. 
PUSHBUTTON 5. - mWin2.0 mWin30 mWin3.l 
Purpose: . Defines a pushbutton for a dialog box. : 
Syntax : PUSHBUTTON teat, id, x, y, width, height, [style] 
Example ‘ PUSHBUTTON “Done”, DLI_DONE, ‘40, 10, 40, 15, WS_TABSTOP 
Description Dialog boxes usually have at least one PUSHBUTTON (or DEFPUSHBUTTON) control to allow the 
. 7 user to exit the dialog box. The allowed-styles are WS_TABSTOP, WS_DISABLED, and 
WS_ GROUP. 7 
RADIOBUTTON mWin2.0 mWin3.0 mWin3.1 
Purpose Defines a radio button control in a dialog box. 
Syntax RADIOBUTTON text, id, x, y, width, height, [style] : 
Example RADIOBUTTON “Select Option ON”, DLI_RADIOI, 10, 10, 40, 15 
Description ~ Radio buttons are usually used in groups to specify selection of one out of a limited number of 
choices. Radio buttons belong to the “button” window class. See the CheckRadioButton() func- 
_ tion description later in this chapter for an example. 
RTEXT | | -mWin2.0 wmWin3.0 mWin3.l 
Syntax - RTEXT text, id, a, y, width, height, [style] . 
Example 
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Description This control places static text in a dialog box. The text is justified to the right border within the 
bounds of the rectangle specified by x, y, width, height. Normally, static text controls are given 
an ID value of —1, as they are never selected. An exception is when the dialog box function 
changes the text content as the dialog box operates. 

SCROLLBAR mWin2.0 mWin30 m Wind 

Purpose Defines a scroll bar control within a dialog box. 

Syntax SCROLLBAR 1d, x, y width, height, (style) 

Example SCROLLBAR DLI_SCROLL, 50, 10, 8, 50, SBS_VERT 

Description Scroll bar-controls are excellent ways of getting user input for scaleable items, such as integers. 


Scroll bars can also be used to scroll the client area of a window, but this is unlikely with a dialog 
box. The most common styles are SBS_VERT for vertical scroll bars, and SBS_HORZ for horizon- 
tal ones. See Table 2-3 under the CreateWindow() function description for a full list of scroll bar 
styles. 


Dialog Box Function Summaries 
Table 13-1 summarizes the dialog box functions. The detailed function descriptions are in the next section. 


CheckDigButton 


Checks or removes a check from a dialog box control. 


CheckRadioButton Changes the selected item from a group of radio buttons. 
CreateDialog Creates a modeless dialog box. 
CreateDialogindirect Creates a modeless dialog box. 
~ CreateDialogindirectParam Creates a modeless dialog box, and passes a 32-bit value to the dialog box function when it 
starts processing messages. 
CreateDialogParam Creates a modeless dialog box, and passes a 32-bit ate to the dialog box function when it — 
Starts processing messages. 
DefDigProc Provides default message processing logic for dialog boxes created with ther o own, separate 
window class. 
DialogBox Creates a modal dialog box. 


Dalogbinect 


Creates a modal dialog box. 


DilogBoxinrectParam Creates a modal dialog box, and passes a 32-bit data item to the dialog box as it is created. 
DialogBoxParam Creates a modal dialog box, and passes a 32-bit data item to the dialog box as it is created. 
EndDialog Closes a modal dialog box, and returns control to the calling function. 

GetDialogBaseUnits Determines the size of the dialog base units used to create dialog boxes and position conirols. 
GetDigCtrilD Retrieves a dialog box control's ID values given the control's window handle. 

GetDigltem Retrieves the window handle for a dialog box control, given the control’s |D number. 
GeiDigitemint Retrieves an integer value from a control in a dialog box. 

GetDigltemText Retrieves a character string from an edit control in a dialog box.: 

GetNextDigGroupitem Finds the next (or previous) window handle of the dialog box contro! that will receive the input 


focus if the user presses the arrow Keys. 


565 


WINDOWS API BIBLE 


Table 13-1. continued 


GetNextDigTabitem » Finds the next (or previous) window handle of the dialog box control that will receive the input 
focus if the user presses the key. 
IsDialogMessage Determines if a message is meant for a dialog box. 
IsDigButtonChecked Determines if a check box or radio button control is checked. 
MapDialogRect Converts from dialog base units to screen units (pixels). 
MessageBox Creates and displays a small window containing a message. 
SendDigltemMessage Sends a dialog box control a message. . 
SetDigltemint Changes the text in a dialog box control toan integer value. 
SetDigltemText. ’ Changes the text in a dialog box control. 


Table 13-1. Dialog Box Function Summaries. 


Dialog Box Function Descriptions 
This section combines the detailed dese DHONS for the gee box functions. 


@ Win 2.0 


eWin3.0 mWind3l 


Doltl Quit 


The current values are: 1.0 


2. Example Dialog Box’. o4 2 


Title String Here 
Check box control. 


Radio buttons. 


CueckDicGBurron 

Purpose “Checks or removes a check from a dialog box control. 

Syntax void CheckDIgButton(HWND Dig, int nJdButton, WORD wCheck); | 

Description This isa shortcut method for inserting and removing checks from dialog box controls. It is used 
with the BS_CHECKBOX and BS_38STATE types of buttons. Using CheckD]gButton() is equiva- 
lent to sending a BM_SETCHECK message to the dialog box control . 

Uses Used with check boxes and three-state buttons to insert and remove the eheceInanN from the 
control. 

Returns No returned value (void). 

See Also CheckRadioButton(), CheckMenultem() 

Parameters 

hDig HWND: The dialog box window’s handle. 

nidButton int: The control ID for the check box or three-state button. 
Control ID values are normally defined in a header file. 

wCheck WORD: Set to 0 to remove the checkmark. Set to 1 to set the 

_ checkmark. For three-state buttons, set to 2 to gray the check 

box. Settings of 0 and 1 have the same effect on check boxes 
and three-state buttons. 

Related Messages BM_SETCHECK 

Example This example, which is illustrated in Figure 18-3, displays a 


modal dialog box when the user clicks the “Do It!” menu item. 
The dialog box contains a check box and a set of two radio but- 
tons. Both controls provide a way to show a selection. The 
check box is best used for an on/off choice. Groups of radio 
buttons are better for selections from, a set of mutually exclu- 
sive choices. 


OFirst; 
O Second 


= 


Figure 13-3. CheckDig- 
Button() and CheckRadio- 
Bution() Example, — 


The dialog box is defined in a .DLG file created with the SDK Dialog Box Editor. 
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> GENERIC.DLG Dialog Box Definition File 


EXMPDLG DI 
CAPTION "E 


ALOG LOADONCALL MOVEABLE PISCARDABLE 10, 18, 139, 75 
xample Dialog Box" 


FONT 10, “Helv" 
STYLE WS_BORDER | WS_CAPTION | WS_DLGFRAME | WS_POPUP 


BEGIN 
CONTROL 


CONTROL 


CONTROL 


CONTROL 


CONTROL 


CONTROL 


CONTROL 


END 


“Title String Here", -1, "static", 
SS_CENTER | WS_CHILD, 27, 6, 78, 9 
"Check box control.", -1, "static", 
SS_LEFT | WS_CHILD, 60, 22, 67, 9 
“Radio buttons.", -1, “static”, 
SS_LEFT | WS_CHILD, 60, 39, 73, 10 
"DONE", DLI_DONE, "button", 
BS_DEFPUSHBUTTON | WS_TABSTOP | WS_CHILD, 72, 59, 36, 12 
"«) DLI_CHECKBOX, "button", 
BS_CHECKBOX | WS_TABSTOP | WS_CHILD, 7, 24, 16, 9 : 
“First", DLI_RADIO1, "button", 
BS_RADIOBUTTON | WS_TABSTOP | WS_CHILD, 6, 36, 28, 12 
"Second", DLILRADIO2, "button", 
BS_RADIOBUTTON | WS_TABSTOP | WS_CHILD, 6, 47, 44, 12 


In addition te the DLG file, a header file containing the definitions of the dialog control IDs 
(DLI_DONE, etc.) and a standard header file containing the function declarations are needed. 
This file can be created from within the Dialog Box Editor. 


C> GENERIC.HD Dialog Box Item Defines 


#define DL 
Hdefine DL 
Hdefine DL 
#define DL 


I_CHECKBOX 101 
I_DONE 102 

I_RADIO1 —- 103 
I_RADIO2 104 


The program’s resource file includes the dialog box definition file (.DLG file) and the header 
file containing the dialog box ID value (.HD file). 


CG GENERIC.RC Resource Definition File 


/* generic. 


#include < 
#include 
Hinclude 
#include 


generic 


generic 
BEGIN 
MENUITE 
MENUITE 
END 


int nCheck 
int nRadio 


{ 


rc x] 


windows.h> 


“generic.h" 
“generic.hd" 
"generic.dlg” 


ICON ‘generic.ico 


MENU 
M"&Do It!" IDM_DOIT 
M“SQuit", IDM_QUIT 


The dialog box function DialogProcedure() at the end of the listing shows typical program 
logic for handling check boxes and radio buttons. The current status of each of the button groups 
is held in two global variables, nCheckOne and nRadioOne. Use of global variables allows the 
WndProc() function to keep track of the button status. A function prototype for 
DialogProcedure() must be included in the program’s header file and listed in the EXPORTS 
section of the program’s .DEF definition file. 


0; 
0; 


One 
One 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
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PAINTSTRUCT ps; 

static FARPROC lpfnDialogProc ; 

static char cBuf [256] ; 

switch (iMessage) /* process windows messages */ 


{ 
: case WM_PAINT: : 
BeginPaint (hWnd, &ps) ; 
TextOut (Cps.hde, 10, 10, cBuf, wsprintf (cBuf, 
* "The current values are: %d, %~d", 
nCheckOne, nRadioOne)) ; 
EndPaint (hWnd, &ps) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
\ : 

case IDM_DOIT: /* User hit the “Do it” menu item */ 

ipfnDialogProc = MakeProcInstance 
(DialogProcedure, ghInstance) ; 

DialogBox (ghInstance, “exmpdlg", hWnd, . 


: LpfnDialogProc) ; 
FreeProcInstance (lpfnDialogProc):; 
InvalidateRect (hWnd, NULL, TRUE) ; /* force paint */ 
break ; 
case IDM_QUIT: 
: DestroyWindow (hWnd) ; 


break ; 
} 
break ; . 
case WM_DESTROY: /* stop application */ 
' PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 


return DefWindowProc ChWnd, iMessage, wParam, LParam) ; 
} 
return (OL) ; 
} 


BOOL FAR PASCAL DialogProcedure CHWND hDlg, unsigned iMessage, WORD wParam, LONG lParam) 
{ : 
BOOL bBool ; 


switch (CiMessage) 
t 
case WM_INITDIALOG: 
if (nCheckOne) 
CheckDlgButton (hDlg, DLI_CHECKBOX, MF CHECKED) ait 
else 
CheckDligButton (hDlg, DLI_CHECKBOX, MF_UNCHECKED) ; 


if (nRadioOne) 
CheckRadioButton (hDlg, DLI_RADIO1, DLI_RADIO2, 
DLI_RADI02)_; 
else 
CheckRadioButton (hDlg, DLI_RADIO1, DLI_RADI02, 
DLI_RADIO1) ; 
break ; , 
case WM_COMMAND: 
switch (wParam) 
{ 
case DLI_CHECKBOX: | 
if (nCheckOne) 


{ ° 
nCheckOne = 0; ., 
CheckDlgButton (hDlg, DLI_CHECKBOX, 
MF_UNCHECKED) ; 
} 


else 
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{ 
nCheckOne = 1 ; 
CheckDlgButton (hDlg, DLI_CHECKBOX, 
MF_CHECKED) ; 
} ; 


return (TRUE) ; 
case DLI_RADIO1: 
nRadioOne = 0 ; 
CheckRadioButton (hDlg, DLI_RADIO1, DLI_RADIO2, 
DLI_RADIO1) ; 
return (TRUE) ; 
case DLI_RADIO2: 
nRadioOne = 1 ; 
CheckRadioButton (hDlg, DLI_RADIO1, DLI_RADIO2, 
DLI_RADIO2) ; 
return (TRUE) ; 
case DLI_DONE: 
EndDialog (hDlg, NULL) ; 
return (TRUE) ; 


} 
break ; 

default: 
return (FALSE) ; 

} 

return (FALSE) ; 

} 

CHECKRADIOBUTTON mWin2.0 mWin3.0 mWin3.1 

Purpose Changes the selected item from a group of radio buttons, 

Syntax void CheckRadioButton(HWND ADig, int nJDFirstButton, int nIDLastButton, int 

nlIDCheckBution), 

Description Radio buttons are used in groups to show a selection from a group of mutually exclusive choices. 
CheckRadioButton() works best if all of the related radio buttons are given ID values in sequential 
order. CheckRadioButton() will update the group of buttons in one function call to show a new 
selection. This function is equivalent to sending each of the buttons a BM_; SETCHECK oes 

Uses Changing a group of radio buttons to reflect a selection. 

Returns No returned value (void). 

See Also CheckDigButton(), CheckMenultem() 

Parameters 

hDlg HWND: The dialog box window’s handle. 

nIDFirstButton int: The ID value for the first radio button control of the group. The group of related radio buttons 
is assumed to be numberd in sequential order. 

nIDLastButton int: The ID value for the last radio button control of the group. 

nIDCheckButton int: The ID value for the radio button control that should show a checkmark. All of the other 
radio buttons in the group will have their checkmarks removed. 

Related Messages WM_SETCHECK 

Example See the previous example under CheckD]gButton(). 

CREATEDIALOG _ i | mWin2.0 mWin3.0 mWin3l 

Purpose Creates a modeless dialog box. 

Syntax HWND CreateDialog(HANDLE hinstance, LPSTR ees aun hWndParent, 


FARPROC [pDialogFunc); 
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Description 


Uses 


Returns 
See Also 


Parameters 
hInstance 
lpTemplateName 


hWndParent 


IpDialogFunc 


hDig 
wMsg 
wParam 
lParam 


Related Messages 
Example 


A modeless dialog box behaves like a popup window. The user can switch the focus to the parent 
window, or another application, while the modeless dialog box is still visible. The dialog box 
template file should contain the WS_VISIBLE style. If not, the ShowWindow() function will be 
needed to make the modeless dialog box visible. Unlike DialogBox(), CreateDialog() returns im- 
mediately, returning the handle of the dialog box window created. Modeless dialog boxes are 
ended by calling DestroyWindow() within the dialog box function. The application’s message 
loop needs to be modified for modeless dialog boxes, so that keyboard input to the dialog box is 
properly processed. See the example below for the proper use of the IsDialogMessage() function. 


Modeless dialog boxes are convenient for tool windows that may remain on the screen for an 
extended period of time. — 
HWND, the handle to the muucieless dialog box created. 


CreateDialogIndirect(), CreateDialogParam(), DestroyWindowQ), IsDialogMessage(), Set- 
Focus(), DialogBoxQ) 


HANDLE: The program’s instance handle. 


LPSTR: A pointer to a character string containing the name of the dialog box template in the 
application’s resource file. Dialog box templates are eM created with the SDK Dialog Box 
Editor. 
HWND: The parent window's handle. Destroying the parent window will automatically destroy 
the modeless dialog box. — | 
FARPROC: The procedure-instance address of the dialog box function. This address is created 
with MakeProcInstance(). The dialog box function processes messages for the dialog box. This 
function must be declared in the EXPORTS section of the program’s .DEF definition file, and it 
must have the following format: 

BOOL FAR PASCAL DialogFunc(HWND hDig, WORD wMsg, WORD wParam, DWORD [Param); 
The parameters passed to the dialog box function have the following meanings. 


HWND: This is the window handle for the modeless dialog box window. This handle can be used 
just like any other window handle for setting colors, changing the caption, etc. 


WORD: The message being passed to the dialog function. For example, WM_ INITDIALOG i 1S sent 


‘to the dialog function right before the window is made visible. 


WORD: The WORD data associated with the message. 


DWORD: The 32-bit data associated with the message. 

The dialog box function should return TRUE if the function processes the message, and 
FALSE if the message is not acted on. The exception is processing a WM_INITDIALOG message. 
In this case, the function should return TRUE only if the SetFocus() function is not called, FALSE 
if SetFocus() is called. SetFocus() is used to establish which control will have the input focus 
when the dialog box is first made visible. If SetFocus() is not used, the first control in the paaloe 
box definition receives the input focus. 


WM_INITDIALOG 


This example creates the same dialog box shown i in the example under CheckDigButton(), ex- 
cept that the dialog box is a modeless dialog box. This means that the dialog box behaves like a 
popup window. The focus can be switched from the dialog box to the main window or other win- 
dows on the screen. The dialog box definition is identical to the one for a normal (modal) dialog 
box, except that the window style includes WS_VISIBLE. This avoids having to call the 
ShowWindow() function to make the modeless dialog box visible. 
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EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE O, 0, 139, 75 

FONT 10, “Helv” 

CAPTION "“Modeless Dialog box" 

STYLE WS_BORDER |-WS_DLGFRAME | WS_CAPTION | WS_POPUP | WS_VISIBLE 


BEGIN 


CONTROL “Title String Here", -1, “static”, 


CONTROL 
CONTROL 
CONTROL 
CONTROL 
CONTROL 
CONTROL 


END 


SS_CENTER | WS_ CHILO, 27, 6, 78, 9 
“Check box control.", -1, “static", 

SS_LEFT | WS_CHILD, 60, 22, 67, 9 
“Radio buttons.", -1, "static", 

SS_LEFT | WS_CHILD, 60, 39, 73, 10 
"DONE", DLI_DONE, “button", 

BS_DEFPUSHBUTTON { WS_TABSTOP } “WS CHILD, 72, 59, 36, 12 
“ OLI CHECKBOX, "button", 

. BS_CHECKBOX | WS__ TABSTOP { WS_CHILD, ?, 24, 16, 9 

"First", DLI_LRADIO1, "button", 

BS RADIOBUTTON | WS_TABSTOP | WS_CHILD, 6, 36, 28, 12 
“Second”, DLI_RADIO2, “button", 

BS_RADIOBUTTON | WS_TABSTOP | WS_CHILD, 6, 47, 44, 12 
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The C program uses CreateDialog() to start the modeless dialog box when the user clicks the “Do It!” menu item. 
The logic shown is incomplete, as this program allows any number of modeless dialog boxes to be created by repeat- 
edly clicking the menu item. Note that the handle for the dialog box hDlgModeless is defined as a global variable at the 
top of the listing. This handle is used in the window's message loop to check whether the dialog box is present. If it is, 
IsDialogMessage() is used to screen keyboard input and translate it as necessary for the dialog box to process. Dialog 
box messages are not sent to the window’s WndProc() function with DispatchMessage(). 

In the dialog box function at the bottom of the listing, note that DestroyWindow() is used to end the dialog box. 
Also note that the hDlgModeless handle is set back to zero, shutting down the dialog box message interception in the 
application's message loop. . 


/* generic. 


#Hinclude <windows.h> 


c */ 


#inctude “generic.h” /* the application's header file */ 
#include “generic.hd" 


int 
int 
HWND 


nCheckOne = 0; ‘* globals */ 
nRadioOne = 0 ; 
hDtgModeless = 0 ; 


/* window's header file - always included */ 


int PASCAL WinMain (HANDLE hInstance, HANDLE hPrevinstance, LPSTR LpszCmdLine, int. nCmdShow) 
t /* variable types defined in windows.h */ 


HWND » hWnd ; /* a handle to a message */ 

MSG - msg ; _ /* a message */ 

WNDCLASS wndclass ; /* the window class */ 

ghinstance = hInstance ; /* store instance handle as global var. */ 

if (!hPrevinstance) /* Load data into window class struct. */ 

{ 
wndclass.style = CS_HREDRAW | CS_VREDRAW ; 
wndclass.lpfnWndProc = WndProc ; 
wndclass.cbClsExtra =0; ; -- 
wndclass.cbWndExtra =0; 
wndclass.hInstance = hInstance ; ; 
wndclass.hIcon = Loadicon (hInstance, gszAppName) ; 
wndclass.hCursor = LoadCursor (NULL, IDC_ARROW) ; 
wndclass.hbrBackground = GetStockObject CWHITE_BRUSH) ; 
wndclass.lpszMenuName = gszAppName ; 
wndclass.lpszClassName = gszAppName ; : 

\ /* register the window class */ 
if (!RegisterClass (&wndclass)) _—~ 
; _Peturn FALSE ; 
} , 
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} 


hWnd = CreateWindow (¢ = /* create the program's window here */ 
gszAppName, /* class name */ 
gszAppName, /* window name */ 
WS_OVERLAPPEDWINDOW, /* window style */ 
CW_USEDEFAULT, /* x position on screen */ 
CW_USEDEFAULT, /* y position on screen */ 
CW_USEDEFAULT, /* width of window */ 
CW_USEDEFAULT, /* height of window */ 
NULL, /* parent window handle (null = none) */ 
NULL, /* menu handle (null = use class menu) */ 
hInstance, . /* instance handle */ 
NULL) >; /* tpstr Cnull = not used) */ 
ShowWindow (hWnd, nCmdShow) ; Je 
UpdateWindow (hWnd) ; /* send first WM_PAINT message */ 


while (GetMessage (&msg, NULL, 0, Q)) /* the message loop */ 
{ a ; 

if ChDlgModeless == NULL ]}] 

'IsDialogMessage (hDlgModeless, &msqg)) 
TranslateMessage (&msq) ; 
DispatchMessage (&msqg) ; 
} 

} 
return msg.wParam ;. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG |LParam) 


{ 


} 


t 


BOOL FAR PASCAL DialogProcedure (HWND hDlg, unsigned iMessage, WORD wParam, LONG lParam) 


PAINTSTRUCT ps >; 
static FARPROC lLpfnDialogProc ; 
static char cBuf (256) >; 


switch CiMessage) /* process windows messages */ 
case WM_PAINT: 
BeginPaint (hwnd, &ps) ; : ; 
TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
¢ “The current values are: %d, 4d", 
nCheckOne, nRadioOne)) ; 
EndPaint ChWnd, &ps) ; 
break ; 
case WM_COMMAND: 
switch (wParam) 
{ . 
case IDM_DOIT: -/* User hit the “Do it” menu item */ 
beim islosPros, = MakeProcInstance (DialogProcedure, 
ghInstance) >; 
“‘Rilgnodateaa = CreateDialog (ghInstance, "exmpdlg", 
hWnd, tpfnDialogProc) ; 


/* process menu items */_ 


break ; 
case IDM_QUIT: 
DestroyWindow ChWnd) ; 
break ; 
} 
as break ; 
case WM_DESTROY: /* stop application *] 
FreeProcInstance <{pindialogProc) 
PostQuitMessage (0) ; 
break ; ; 
default: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
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BOOL bBool ; 


switch (iMessage) 
{ 
case WM_INITDIALOG: © 
if (nCheckOne) 
CheckDlLgButton (hDlg, DLI_CHECKBOX, MF_CHECKED) ; 
else : 
CheckDlgButton ChDlg, DLI_CHECKBOX, MF_UNCHECKED) ; 


if (nRadioOne) 
CheckRadioButton (hDig, DLI_RADIO1, DLI_RADIO2, 
DLI_RADIO2) ; 
else 
CheckRadioButton ChDtg,: ‘DLI_RADIO1, DLI. —RADIO2, 
DLI_RADIO1) >; 
return (TRUE) ; 
case WM_COMMAND: 
switch (wParam) 
{ 


case DLI- CHECKBOX: 
if (nCheckOne) 


{ 

nCheckOne = O ; 

checkDL GbuERoR ChDlg, DLI_CHECKBOX, MF _UNCHECKED) ; 
} 
else 
{ 

“nCheckOne = 1 7 

checkDLgBut ton Chdlg, DLI_CHECKBOX, MF_CHECKED) ; 

} 


return (TRUE) ; 
case DLI_RADIO1: 
nRadioOne = 0 ; 
CheckRadioButton ChDlg, DLI_RADIO1, DLI_RADIO2, 
DLI_RADIO1) ; 
return (TRUE) ; 
case DLI_RADI02: 
? nRadioOne = 1 ; 
CheckRadioButton ChDlg, DLI_LRADIO1, DLI_RADIO2, | 
DLI_LRADIO2) ; - 
return (TRUE) ; ; 
case DLI_DONE: 
DestroyWindow ChDlg) 7; 
hDlgModeless =0; ° 
return (TRUE) ; 
} 
break ; 
default: 
return CFALSE) ; 


. atuien CFALSE) ; 

CREATEDIALOGINDIRECT _ mWin20 mWin3.0 mm Win ay 

Purpose Creates a modeless dialog box. 

Syntax HWND CreateDialogIndirect(HANDLE hinstance, LPSTR lpDialogTemplate, HWND hWnd- 
or Parent, FARPROC [pDialogFunc); 

Description This function is identical to CreateDialog(), except that the dialog template is specified with a 


pointer to memory containing a dialog box template. The dialog box template can be either cre- 
ated from scratch in memory, or loaded into memory from a dialog box resource. The structure of 
the dialog box definition in memory is discussed at the beginning of this chapter under the head- 
ing Dynamic Dialog Boxes. 
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Uses 


Returns 
See Also 
Parameters 


hInstance 
lpDialogTemplate 


hWndParent 


lpDialogFunc 


hDig 
wMsg 


wParam 
lParam 


Related Messages 
Example 


This function can be used to create modal dialog boxes that can be modified as the program runs 
(called “dynamic dialog boxes”). Typical applications are database programs, with which the 
user can add or subtract fields from the database. Using this function provides greater control 
over when the program loads and discards the resource data that defines the dialog box. This can 


be important in applications that use a large number of resources and need to control which ones - 


are preloaded, and which are discarded. 


Modeless dialog boxes are convenient for tool windows that may remain on the screen for an 
extended period of time. 


CreateDialog(),. CaaeiiaanaanG, DesreyMndeng: IsDialogMessage(), SetFocus(), 
DialogBox() 


HANDLE: The program’s instance handle. 


LPSTR: A pointer to a memory area containing the dialog definition. The definition can be cre- 


ated in a global memory block, and then locked with GlobalLock(). Alternatively, the dialog defi- 
nition can be loaded from a resource with Leadiresource() and locked with LockResource() prior 
to calling CreateDialogIndirect(). 


HWND: The parent window's handle. Destroying the parent window will automatically destroy 
the modeless dialog box. 


FARPROC: The procedure-instance address of the dialog box function. This address is created 
with MakeProcInstance(). The dialog box function processes messages for the dialog box. This 
function must be declared in the EXPORTS section of the program’s .DEF definition file, and 
must have the following format: 


BOOL FAR PASCAL DialogFunc(HWND hDlg, WORD wMsg, WORD wParam, DWORD /Param), 
The parameters passed to the dialog box function have the following meanings. 


_HWND: This is the window handle for the modeless dialog box window. This handle can be used 


just like any other window handle for setting cotors, changing the caption, etc. 


WORD: The message being passed to the dialog function. For example, WM_INITDIALOG is sent 
to the dialog function right before the window ee visible. 


WORD: The WORD data associated with the message. 


DWORD: The 32-bit data associated with the message. 

The dialog box function should return TRUE if the function processes the message, and 
FALSE if the message is not acted on. The exception is processing a WM_INITDIALOG message. 
In this case, the function should return TRUE only if the SetFocus() function is not called, FALSE 
if SetFocus() is called. SetFocus() is used to establish which contro] will have the input focus 
when the dialog box is first made visible. If SetFocus() is not used, the first contro] in the dialog 
box definition receives the input focus. 


WM_INITDIALOG . 
This example creates the dialog box definition in memory by loading a dialog box resource. The 


result is identical to the one shown in more detail under CreateDialog(). The only differences are 
in the processing of the IDM_DOIT menu item. Because CreateDialogIndirect() is used to create 


the modeless dialog box, some preparation is required. First, the dialog box information is loaded ° 


into memory with LoadResource(). Second, the memory block containing the dialog box informa- 
tion is locked in memory using LockResource(). LockResource() returns a handle to the memory 
area, needed to call CresteDinloginatrentt): As the ee boxi is created, els memory a area can be 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG {Param) 
{ 
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PAINTSTRUCT ps ; 


static FARPROC LpfnDialogProc ; 

char - cBuf £256] ; 

static ¢ HANDLE hDialog = NULL; 

LPSTR LpResource ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; : 
TextOut (ps.hde, 10, 10, cBuf, wsprintf (cBuf, 
"The current values are: %d, %d", nCheckOne, nRadioOne)) ; 
EndPaint (hWnd, &ps) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ F 
case IDM_DOIT: /* User hit the “Do it" menu item */ . 


_lpfnDialogProc = MakeProcInstance (DialogProcedure, 
ghInstance) ; 
hDialog = LoadResource (ghInstance, 
FindResource (ghInstance, “exmpdlg", RT_DIALOG)) ; 
LpResource = LockResource (hDialog) ; 
hDigModeless = CreateDialogindirect (ghinstance, 
LpResource, - hWnd, lpfnDialogProc) ; 
UnlockResource (hDialog) ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
FreeResource (hDialog) ; 
FreeProcInstance (lpfnDialogProc) ; 
DestroyWindow ChWnd) ; 


break ; 

} o 

break ; 
{Other program lines] 
CREATEDIALOGINDIRECTPARAM gwWin2.0 wWin3d0 mWin3.1 
Purpose “Creates a modeless dialog box, and passes a 32-bit value to the dialog box function when it starts 

processing messages. 
Syntax ‘HWND CreateDialogindirectParam(HANDLE hinstance, LPSTR lpDialogTemplate, HWND 
hWndParent, FARPROC lpDialogFunc, LONG dwInitParam); 

Description This function is identical to CreateDialogParam(), except that the dialog box definition is passed 


as a pointer to a memory area. Like CreateDialogParam(). This function has the added feature of 
allowing a 32-bit item (usually a pointer to a data structure) to be passed to the dialog box func- 
_ tion on startup. 


Uses This is the most sophisticated of the modeless dialog box functions. The function can be used to 
create dynamic dialog boxes that can be changed as the program executes, Using a memory 
" pointer for the dialog resource information, instead of just the dialog box template name, gives 
more control over when the resource data is loaded and discarded. The 32-bit data element al- 
lows the dialog box to avoid global variables as a means of communication between the dialog box 
function and the rest of the application program. 


Returns . HWND, the handle to the modeless dialog box created. 

See Also CreateDialog(), CreateDialogIndirect(), DestroyWindow(), IsDialogMessage(), SetFocus() 
Parameters i 

hInstance HANDLE: The program’s instance handle. 


lpDialogTemplate LPSTR: A pointer to a memory area containing the dialog definition. The definition can be cre- 
ated in a global memory block, and then locked with GlobalLock(). Alternatively, the dialog defi- 
nition can be loaded from a resource with LoadResource() and locked with ockresource.) prior 
to calling pail neuen? 
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hWndParent 
lpDialogFunc 


dwinitParam © 


hDig 
wMsg 


wParam 
lParam 


Related Messages 
Example 


HWND: The parent window's handle. Destroying the parent window will automatically destroy 
the modeless.dialog box. 


FARPROC: The procedure-instance address of the dialog box function. This address is created 
with MakeProcInstance(). 


‘ LONG: The 32-bit value passed to the DialogFunc(). Normally this value is used to pee a handle 


to a memory block containing data that the dialog box will use or modify. 

The dialog box function processes messages for the dialog box. This function must be de- 
clared in the EXPORTS section of the program’s .DEF definition file, and must have the following 
format: 

BOOL FAR PASCAL DialogFunc(HWND hDig, WORD wMsq, WORD wParam, DWORD lParam); 
The parameters passed to the dialog box function have the following meanings. 


HWND: This is the window handle for the modeless dialog box window. This handle can be used 
just like any other window handle for setting colors, changing the caption, etc. 


WORD: The message being passed to the dialog function. For example, WM_INITDIALOG is sent 


to the dialog function right before the window is made visible. 
WORD: The WORD data associated with the message. 


DWORD: The 32-bit data associated with the message. The value will be sent as dwInitParam 
when the WM_INITDIALOG message is processed by the dialog box function. 

The dialog box function should return TRUE if the function processes the message, and 
FALSE if the-message is not acted on. The exception is processing a WM_INITDIALOG message. 
In this case, the function should return TRUE only if the SetFocus() function is not called, FALSE 
if SetFocus() is called. SetFocus() is used to establish which control will have the input focus. 
when the dialog box is first made visible. If SetFocus() is not used, the first control in the dialog 
box definition receives the input focus. 


WM_INITDIALOG 


This example is identical to the one under CreateDialogParam(), except for the changes needed 
for CreateDialogIndirectParam(). In both cases the 32-bit value is used to pass the handle to a 
custom data structure TWODATA that contains the settings for the dialog box buttons. See the 
example under CreateDialogParam() for further details. 


typedef struct tagTwoData 
Ct) 


int 
int 
} TWODATA ; 


nOne ;: 
nTwo ; 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ = 


PAINTSTRUCT © 


ps; . 
static FARPROC -->. UpfnDialogProc ; 
static HANDLE _hMem ; 
TWODATA *potd > 
static HANDLE “ hDialog = NULL; 
LPSTR tpResource ; 
switch sitereage? /* process windows messages */ 


case WM_CREATE: 
hMem = Deeatil lee CLMEM_| pevecerr I LMEM |_DISCARDABLE, 
sizeof (TWODATA)) ; 
ptd = CTWODATA *) Letal cock ChMem) ; 
ptd->n0ne = 1 ; 
ptd->nTwo = 1 ; 
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13. DIALOG BOXES V 


break ; 
case Wit_COMMAND: /* process menu items */ 
switch (wParam) ; 
{ 7 
case IDM_DOIT: /* User hit the “Do it" menu item */ 
LpfnDialogProc = MakeProcInstance (DialogProcedure, 
ghInstance) ; 
hDialog = LoadResource (ghInstance, 
FindResource (ghInstance, “exmpdlg", RT_DIALOG)) ; 
lpResource = LockResource C(hDialog) ; 
hDigModeless = CreateDialogIndirectParam 
' (ghInstance, ~° tpResource, hWnd, 
tpfnDialogProc, CDWORD) hMem) ; 
UntockResource ChDialog) ; 
break ; 
.case IDM_QUIT: /* send end of application message */ 
FreeResource (hDialog) ; 
FreeProciInstance (LpfnDialogProc) : 
LocalFree (hMem) ; rs 
DestroyWindow (hwnd) 7 
break ; 


break ; 


_CREATEDIALOGPARAM | , BwWin2.0 mWin3.0 Wind 


Purpose 
Syntax 


Description 


Uses 


Returns 
See Also 


Parameters 
hinstance 


lpTemplateName 


Creates a modeless dialog box, and passes a 32-bit value to the dialog box function when it starts 
processing messages. 


HWND CreateDialogParam(HANDLE hinstance, LPSTR lpTemplateName, HWND hWndParent, 


FARPROC lpDialogFunc, LONG dwInitParam); 


A modeless dialog box behaves like a popup window. The user can switch the focus to the parent 
window, or another application, while the modeless dialog box is still visible. This function is 
identical to CreateDialog(), except that an additional 32-bit value dw/nitParam has been added. 
This value is passed to the dialog box function when the WM_INITDIALOG message is processed. 
The 32-bit value ends up as the /Param value when WM_INITDIALOG is received. The advantage 
of this function is that the 32-bit value can be used to pass a handle to memory containing values 


‘ that the dialog box will change. This avoids having to use global variables for all values changed 
within the dialog box. The dialog box template file should contain the WS_VISIBLE style. If not, 


the ShowWindow() function will be needed to make the modeless dialog box visible. . 

Modeless dialog boxes are ended by calling DestroyWindow() within the dialog box function. 
The application's message loop needs to be modified for modeless dialog boxes, so that keyboard 
input to the dialog box is properly processed. See the example under CreateDialog() for the 
proper use of the IsDialogMessage() function. 


Modeless dialog boxes are convenient for tool windows that may remain on the screen for an | 
extended period of time. 


HWND, the handle to the modeless dialog box created. 


CreateDialog(), CreateDialogIndirect(), DestroyWindow(), Leb ialneMseaeeO) SetFocus), 
DialogBox() 


HANDLE: The program’s instance handle. 


LPSTR: A pointer to a character string containing the name of the dialog box template in the 
application’s resource file. Dialog box templates are normally created with the SDK Dialog Box 
Editor. | 
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hWndParent 


| lpDialogFune 


dwinitParam 


hDig 
wMsg 


wParam 


lParam 


HWND: The parent window's handle. Destroying the parent window will automatically destroy 
the modeless dialog box. 


FARPROC: The procedure-instance address of the dialog box function. This address is created 
with MakeProcInstance(). 


LONG: The 32-bit value passed to the DialogFunc(). Normally, this value is used to pass a handle 
to a memory'block containing data that the dialog box will use or modify. 

The dialog box function processes messages for the dialog box. This function must be de- 
clared in the EXPORTS section of the program’s .DEF definition file, and it must have the follow- 
ing format: 


‘BOOL FAR PASCAL DialogFunc(HWND hDlg, WORD wMsg, WORD wParam, DWORD lParam); 


The parameters passed to the dialog box function have the following meanings. 


HWND: This is the window handle for the modeless dialog box window. This handle can be used 
just like any other window handle for setting colors, changing the caption, etc. 

WORD: The message being passed to the dialog function. For example, WM_INITDIALOG is sent 
to the dialog function right before the window is made visible. 


WORD: The WORD data associated with the message. 


 DWORD: The 32-bit data associated with the message. The value will be the same as 
_dwinitParam with then WM_INITDIALOG message is processed by the dialog box function. 


Related Messages 


Example 


The dialog box function should return TRUE if the function processes the message, and 
FALSE if th -message is not acted on. The exception is processing a WM_INITDIALOG message. 


In this case, the function should return TRUE only if the SetFocus() function is not called, FALSE .. 


if SetFocus() is called. SetFocus() is used to establish which control will have the input focus 
when the dialog box is first made visible. If SetFocus() is not used, the first control in the dialog 
box definition receives the input focus. , 


WM_INITDIALOG 
This example is similar to the one under CreateDialog(), except that CreateDialogParam() has 


been used to avoid global variables. A custom structure called TWODATA is defined to hold the 
two integers needed by the dialog box to control the check box and radio button status. A handle 


. to memory containing this data structure is passed to the dialog box function when — 
_ CreateDialogindirect() is called. The handle ends up as the lParam value passed to 


DialogProcedure() when that function receives the WM_INITDIALOG message. | 
In this case, the data passed in the TWODATA structure is so small that all of the information 


- could be passed in the one 32-bit value (dwInitParam) passed with CreateDialogParam(). The 


reservation of a local memory area for the TWODATA structure is shown as the more general 
case, as usually a dialog box willrequire a number of fields of data, including character strings. 
See the CheckDigButtonQ) function description for a figure showing the appearance of the dialog 
box and other related program files. 


- typedef struct, ‘tagTwodata 
{ 


} TWODATA ; 


Ane 


int 


nOne ; 
nTwo ; 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : 


PAINTSTRUCT ps; . 
static FARPROC - LpfnDialogProc ; 
| static HANDLE .  hMem ; 
TWODATA *ptd ; 
“switch (iMessage) © ~~ 7 * process windows messages */ 


} 578 


} 


{ 


case WM_CREATE: 
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hMem = LocalAlloc CLAEN_MOVEABLE | LMEM_DISCARDABLE, 
. sizeof (TWODATA)) > 


ptd = 


ptd->nOne = 1 
ptd->nTwo = 1 
LocalUnlock ¢ 
break ; 


case WM_COMMAND: 
switch (wParam) 
{ 
case IDM_DOIT: 


(TWODATA *) LocalLock ChMem) ; 


; 
? 
hMem) ; 


/* process menu items */ 


/* User hit the "Do it" m 


enu item */ 


LpfnDiatogProc = MakeProcInstance (DialogProcedure, 


ghinstance) ; 


hDlgModeless = CreateDialogParam (ghInstance, 


break ; 
case IDM_QUIT: 


break ; 
} 
break ; 
case WM_DESTROY: 


“exmpdlg", hWnd, lpfnDialogProc, 
CDWORD) hMem) ; 


/* Sene end of application message *. 
DestroyWindow ChWnd) ; 


/*® stop application */ 


FreeProcinscance (lpfnDdialogProc) ; 


LocalFree (hMem) ; 


PostQuitMessage 
break ; : 
default: 


} 
return (OL) ; 


BOOL 
Static 
TWODATA 


HANDLE 


switch (iMessage) 
{ 


case WM_INITDIALOG: 
hMem = LOWORD (lParam) ; 
ptd = 
af Cptd->n0ne) 
CheckDlgButton ¢ 
else 


i 
(0) ; 


/* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, \Param) ; 


bBool ; 
hMem ; 
*ptd ; 


C(TWODATA *) Loca.Lock (hMem) ; 


BOOL FAR PASCAL DiatogProcedure CHWND nDlg, unsigned iMessage, WORD wParam, LONG lParam) ~--. 


hDtg, DLI_CHECKBOX, MF_CHECKED) ; 


CheckDUgputton nota. DLI_CHECKBOX, MF_UNCHECKED) ; 


if (ptd->nTwo) 


CheckRadioButton (hDlg, DLI_RADION, 


DLI_RADI 
else 


DLI_RADI02, 
02) ; 


CheckRadioButton ChDlg, DLI_LRADIO1, DLI_RADIO2, 


DLI_RADI 
LocalUntock ChMem) ; 
return. (TRUE) ; 
case WM_COMMAND: 


01) ; 


“ptd = CTWODATA *) LocalLock ChMem) ; 
switen (wParam) 
{ 


case DLI_CHECKBOX: 
if (ptd->n0ne) 
C 


ptd->nOne = 0 ; 


CheckDlgButton ChDdlg, DLI_ CHECKBOX, 


else 


MF_UNCHECKED) ; 
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default: 


} 


-?} 


{ : 
ptd->nOne = 1 ; : 
CheckDlgButton (hDlg, DLI_CHECKBOX, 
MF_CHECKED) ; 
} 


LocalUnlock ChMem) ; 
return (TRUE) ; 
case DLI_RADIO1: 
ptd->nTwo = 0 ; 
* CheckRadioButton ChDlg, DLI_RADIO1, DLI_RADIO2, 
DLI_RADIO1) ; 
LocalUnlock Chiiem) : 
return (TRUE) ; 
case DLI_RADIO2: 
ptd->nTwo = 1 ; 
CheckRadioButton ChDlg, DLI_RADIO1, DLI_RADIO2, 
DLI_RADIO2) ; 
LocalUnlock (hMem) ; 
‘ return (TRUE) ; 
case DLI_DONE: 
DestroyWindow (hDlg) > 
hDigModeless = 0; 
LocalUnlock ChMem) ; 
return (TRUE) ; 


break ; 


return (FALSE) ; 


return (FALSE) ; 


} 


-DerDiGPrRoc 


Purpose 


mWin2.0 @8Win3.0 mWind! 


Provides default message processing logic for dialog boxes created with their own separate win- 


Uses 
Returns 
Parameters 
hDlig 

wMsg 


' wParam 


lParam 


dow class, 
LONG DefDigProc(HWND hDig, WORD wifsg, WORD wParam, LONG lParam); 


Normally, Windows takes care of processing messages that the dialog box function does not 
handle. An exception is when a separate window class is used for the dialog box window. To do 
this, include the CLASS statement in the dialog box definition in the program’s resource file. 
The window class must be registered with RegisterClass() before the dialog box is called. 
The dialog window class must include the DLGWINDOWEXTRA value for the cbWndExtra ele- 
ment of the class structure. This provides extra data space in the class definition. Because the 
class definition includes a pointer to the dialog box function, it is not necessary to specify the 
procedure-instance address of the dialog box function when calling DialogBox() or the other . 
related functions. 


Only used with dialog boxes that snide the CLASS statement to specify a separate window class. 
This is unusual, and is not encouraged in the Windows SDK documentation. 


LONG, the value returned by DefD|gProc() is returned to Windows after the message is processed 


(see the usage at the bottom of the example listing). 


HWND: The dialog box window handle. 


WORD: The message ID value, such as WM_INITDIALOG. Messages that are not ieee bythe — 
dialog box function logic are passed to DefDIgProc(). 


'- WORD: The WORD parameter passed to the dialog box function. 
_ _DWORD: The DWORD parameter passed to the dialog box function. 


580 


13. DIALOG BOXES Vv 


Related Messages All Windows messages that are not processed by the dialog box function should be passed to 
DefD1gProc() if the dialog box has its own window class. 


Example The dialog box resource definition has had the CLASS statement added. In this case, the dialog 
box will use the “separate” class when the dialog box is created and shown. Otherwise, the dialog 
box is identical to the one shown in Figure 18-3, under the CheckDigButton() function descrip- 
tion. That description also includes listings of the header files and .DEF definition file> 


EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE 10, 18, 139, 75 
CAPTION “Example Dialog Box" 
FONT 10, “Helv" 
STYLE WS_BORDER | WS_CAPTION ie WS_DLGFRAME 1 WS. a ORER | WS_VISIBLE 
CLASS “separate" 
BEGIN 
CONTROL "Title String Here", -1, "static", 
: SS_CENTER | WS_CHILD, 27, 6, 78, 9 

CONTROL "Check box control.", -1, "static", 

SS_LEFT | WS_CHILD, 60, 22, 67, 9 
CONTROL "Radio buttons.", -1, "static", 

SS_LEFT | WS_CHILD, 60, 39, 73, 10 
CONTROL "DONE", DLI_DONE, “button", 

BS_DEFPUSHBUTTON | WS _TABSTOP | WS_CHILD, 72, 59, 36, 12 
CONTROL “", DLI_CHECKBOX, “button", ; 

BS_CHECKBOX | WS_TABSTOP | WS_CHILD, 7, 24, 16, 9 
CONTROL "First", DLI_RADIO1, “button", 

BS “ RADIOBUTTON | WS_TABSTOP {| WS —CHILD, 6, 36, 28, 12 

CONTROL “Second”, DLI_RADIO2, "button", 

BS_RADIOBUTTON | WS_TABSTOP | WS_CHILD, 6, 47, 44, 12 
END 


Note that the separate class for the dialog box is created in WndProc() when the 
WM_CREATE message is processed. The class definition specifies the IDC_CROSS cursor shape 
instead of the normal IDC_ARROW. Note that this change only applies to the dialog box window 

_ Class, not to the class upon which the dialog box controls are based. The result is that the cursor 
shape is a cross when the mouse points to an area on the dialog box window, but it switches to an 
arrow when the mouse points to one of the dialog box controls. 


\ 


/* generic.c */ 


Hinclude <windows.h> : /* window's header file - always included */ 
#include "generic.h"” /* the application's header file */ 
Hinclude “generic.hd" ; 


int nCheckOne 
int nRadioOne ; 7 
HWND hDlLaModeless = 0 ; ; ee 


0; /* globals */ 
0 


int PASCAL WinMain CHANDLE hinstance, HANDLE epeUTAREAnGes LPSTR lpszCmdLine, int n¢mdShow) 


\ wndclass.hInstance 
wndclass.hIcon 


hInstance ; 
LoadiIcon (hInstance, aeznpplanes 2 


{- : /* variable types defined in windows.h */ 
HWND hWnd ; /* a handle to a message */ 
MSG msg ; - /* a message */ 
WNDCLASS . wndclass ; /* the window class */ 
ghIinstance = hInstance ; /* store instance handle as global var. */ 
if ('hPrevInstance) /* Load data into window class struct. */ 
{ 
wndclass.style = cs _HREDRAW. | CS_VREDRAW ; 
wndclass.lpfnWndProc = WndProc ; 
wndclass.cbClsExtra =O; 
wndclass.cbWndExtra =0; 
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LoadCursor (NULL, IDC_ARROW) ; 
wndclass.hbrBackground GetStockObject (WHITE_BRUSH) ; 
wndclass.lpszMenuName gszAppName ; 
wndclass.lpszClassName = gszAppName'; 
/* register the window class */ 
if (!RegisterClass (&wndclass)) 
return FALSE ; 


‘wndelass.hCursor 


ao tt 


} 
hwnd = CreateWindow (¢ /* create the program's window here */ 
; gszAppName, /* class name */ . 
. gszAppName, /* window name */ 
WS_OVERLAPPEDWINDOW, /* window style */ 
7 CW_USEDEFAULT, . /* x position on screen */ 
: ' CWLUSEDEFAULT, /* y position on screen */ 
"CW_USEDEFAULT, /  /* width of window */ 
CW_USEDEFAULT, /* height of window */ 
NULL, = /* parent window handle €null = none) */ 
NULL, /* menu handte (null = use class menu) */ 
hInstance, /* instance handle */ 
~ NULL) ; /* lpstr (null = not used) */ 
ShowWindow ChWnd, nCmdShow) ; : 
UpdateWindow ChWnd) ; /* send first WM_PAINT message */ 
while (GetMessage (&msg, NULL, 0, 0)) /* the message Loop */ 
{ : 
if (hDlgModeless == NULL ]] 
!IsDialogMessage ChDlgModeless, &msg)) 
£ 
TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} 
} 


return msg.wParam 7; 


ighe: FAR PASCAL: WndProc CHWND ode unsigned ifessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT : i 
‘char’ > -- cBut £256] ; 
WNDCLASS : digclass ; 
switch Ciessage? : _7* process windows messages */ 


- case WM_CREATE: 
dlaclass.style 
digclass.lpfnWndProc 
dlgclass.cbClsExtra 
dtgclass.cbWndExtra 

* dlgclass.hInstance 
digclass.hIcon 
_dlgclass.hCursor 
dlgclass.hbrBackground 
dlgctass.lpszMenuName 
digclass.lpszClassName 


CS_HREDRAW | CS_VREDRAw ; 
DialogProcedure ; 

0; : 
DLGWINDOWEXTRA ; 

ghInstance ; 

NULL ; : \ 
LoadCursor (NULL, IDC_CROSS) ; 
GetStockObject (WHITE_BRUSH) ; 
NULL ; 

“separate” >; 


RegisterClass (&dlgclass) ; 
break.; 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
“The current values are: %d, %d", 
nCheckOne, nRadioOne)) ;° 
enerene anuinds &ps) ; . Oy ‘ 
break; 
case WM_COMMAND=: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the “Do it" menu item */. 
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DialogBox (ghInstance, “exmpdlg", hWnd, 
NULL) ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
“case WM_DESTROY: /* stop application */ 
PostQuitHessage (0) ; ‘ 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; i 


} 


Long FAR PASCAL DialogProcedure CHWND hDlg, unsigned iMessage, WORD wParam, LONG LParam) 
t : ; 
BOOL bBoolt ; 


Switch (iMessage) 
t 
case WM_INITDIALOG: 
if (nCheckOne) 
CheckDlgButton ChDig, DLI_CHECKBOX, MF CHECKED) ; 
else 
CheckDtgButton ChDlg, DLI_CHECKBOX, MF_UNCHECKED) ; 


if (nRadioOne) 
CheckRadioButton ChDlg, OLI_LRADIO1, DLI_RADIO2, 7 
. DLI_LRADIO2) ; 
else : 
CheckRadioButton (hDlg, DLI_LRADIO1, DLI_RADIO2, 
DLI_RADIO1) ; 
return (TRUE) ; 
case WM_COMMAND: 
switch (wParam) 


case DLI_CHECKBOX: 
if (nCheckOne) 


{ : 

nCheckOne = 0 ; 

CheckDlgButton ChOlg, DLI_CHECKBOX, MF UNCHECKED) ; 
} 
else 
{ 

nCheckOne =1; | 

CheckDlgButton (hDlg, DLI_LCHECKBOX, MF_CHECKED) ; 
} . 


return (TRUE); 
case DLI_RADIO1: 
fs nRadioOne = 0 ; 
CheckRadioButton Chota, DLI_RADIO1, DLI_RADIO2, 
DLI et DOM ae 
return CTRUE) ; 
case DLI_RADIO2: 
nRadioOne = 1; 
CheckRadioButton ChDtg, DLI_LRADIO1, DLI_RADIO2, 
DLI_RADIO2) ; 
return (TRUE) ; 
case DLI_DONE: 
EndDialog (hDlg, 0) ; 
hDigModeless = 0 ; 
return (TRUE) ; 
} 4 
break ; 
default: 
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} 
} 


DiaALocBox 
Purpose 
Syntax 


Description 


Returns 


See Also 


Parameters 
hinstance 


lpTemplateName 
hWndParent 
lpDialogFunc 


hDig 


wMsg 


wParam 


~ 


. Peturn. (DefDlgProc (hDlg, iMessage, wParam, lParam)) ; 


return (FALSE) ; 


Win 2.0 Win 3.0, Win 3.1 
Creates a modal dialog box. 
int DialogBox(HANDLE hInstance, LPSTR Eee HWND hWndParent, FARPROC 


. lpDialogFunc); 


The dialog box created is application-modal, meaning that the dialog | box window retains the 
input focus for the application until the dialog box is closed. The user can switch to another 
application, but not to another window of the application that called DialogBox(). 

This function is the most common way to create a dialog box. The dialog box template is 
defined in the program’s .RC resource file. A dialog box function must be defined to process 
messages while the dialog box is in operation. Messages pass through this dialog procedure until 
the procedure calls EndDialog(). The dialog box function must be listed in the EXPORTS section 
of the program’s .DEF definition file. Before DialogBox() can be called, the program must obtain 
a procedure-instance address for the dialog box function. A typical set of program lines to run a 
dialog box is as follows: 


static FARPROC LpfnDialogProc ; 


LpfnDialogProc = MakeProcInstance (DialogProcedure, ghinstance) ; 
DialogBox (ghInstance, “exmpdlg", hWnd, lpfnDialogProc) ; 
FreeProcinstance (ltpfnDialogProc) ; ° 


Running a dialog box. The dialog box can be made system-modal by calling SetSysModalWindow(Q) ° 
during the processing of the WM_INITDIALOG message. 


The returned value is equal to the n#esult parameter passed when EndDialog() was called. Using - 
return() inside the dialog function does not result in the value being returned to the application. 
These values are used by Windows. The function returns —1 if the dialog box could not be created. 


DialogBoxIndirect(), DialogBoxIndirectParam(), DialogBoxParam(), 


HANDLE: The application’s procedure-instance handle. 

LPSTR: This is the name of the dialog box template in the program’s .RC resource file. 

HWND: The parent window’s handle. 

FARPROC: The procedure-instance.address of the dialog box function. Use MakeProcinstance() 


- to create this value. The dialog box function must have the following style: 


int FAR PASCAL DialogFunc (HWND hDlg, WORD wMsq, WORD wParam, DWORD lParam); 


The name “DialogFunc” is replaced by the name of the message processing function to use fora 
dialog box. Each dialog box will have a separate “DialogFunc” with a el name. The mean- 
ings of the parameters are as follows. 


HWND: The handle to the dialog box window. This handle can be used just like any other window 
handle: to obtain the device context, to change the caption, etc. , 


WORD: This is the Windows message being passed to the function. For example, wMsg will equal 
WM_INITDIALOG when the dialog box is first started and the first message is sent to the dialog 
box function. 


WORD: This is the WORD parameter passed with the message. Sce Chapter 9, Windows Mes- 
sages, for the meaning of the wParam and (Param values for each message. 
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lParam - DWORD: This is the DWORD parameter passed with the 
message. 

The dialog box function should return TRUE if the func- 
tion processes the message, and FALSE if the message is not 
acted on. The exception is srocessing a WM_INITDIALOG mes- 
sage. In this case, the function should return TRUS only ifthe 
SetFocus() function is not called, FALSE if SetFocus() is 
called. SetFocus() is used to establish which control will have 
the input focus when the dialog box is first made visible. If 
SetFocus() is not used, the first control in the dialog box defi- 
nition receives the input focus. 


TS. VIALUU DUALLY 


The current values are: 44, -245 


input field ono. 


input field two. 


[ Bont. 
Figurel3-4. DialogBox() 
Example. 


Related Messages 


‘Example 


Most Windows messages can be processed by a dialog box. 
WM_CREATE is replaced with WM_INITDIALOG for dialog boxes. . 


This example, shown in Figure 13-4, creates a dialog box for entering two integer values. The 


values are also displayed on the main window's client area, The dialog box style has been changed 
to include a caption bar. This allows the dialog box to be moved on the screen. The dialog box font 
has also been changed to “Helv,” to match the dialog box style used by the dialog boxes in the 
standard Windows applications, such as Paint and Write. 

The dialog resource script that creates the dialog box was originally created with the SDK 
Dialog Box Editor. The .DLG file must be included as part of the program’s .RC file. 


S> GENERIC.DLG 


EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE 10, ae 139, 75 
STYLE WS_DLGFRAME | WS_POPUP | WS_CAPTION 
‘CAPTION “Example Dialog Box" . 
FONT 10, "Helv" SN 
BEGIN 
CONTROL "Title String Here", ~-1, "static", 
SS_CENTER | WS_CHILD, 27, 6, 78, 9 
CONTROL Ta DLI _EDITI, Nedit", 
ES_LEFT | WS “BORDER | ws —TABSTOP 1 WS_CHIL:», 12, 22, 26, 12 
CONTROL “Input field one.", -1, “static”, 
SS_LEFT | WS_CHILD, 60, 24, 67,9 
CONTROL “un DLI_LEDIT2, “edit", 
ES_LEFT | WS_BORDER | WS_TABSTOP | WS_CHILD, 12, 37, 26, 12 
CONTROL “Input field two.", -1, "static", 
SS_LEFT | WS_CHILD, 60, 39, 73, 10 
CONTROL "DONE", DLI_DONE, “button", 
BS_DEFPUSHBUTTON {| WS_TABSTOP | WS_CHILD, 45, 60, 36, 12 
END ; 3 


The dialog box item numbers for the controls are defined in a separate header file, created during 
the SDK Dialog Box Editor session. This file must be included at the top of the resource script .RC 
file and at the top of the C program source file. 


- & GENERIC.HD 


H#define DLI_EDIT1 100 
#define DLILEDIT2 101 
#define DLI_DONE 102 


The program’s header file includes both the dialog box definition file and the dialog box ID value 
file GENERIC.HD. The latter must also be included at the top of the C program file. Note that the 
dialog box function prototype i is included at the end of the header file. 


oe GENERIC. H. 


/* generic.h 1 */ 


H#define IDM_DOIT 1 /* menu item id values */ Ate 
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H#define IDM_QUIT 2 
/* qlobalt variables */ 
int ghinstance ; 
char ae TAcoHine Cj = “generic” 7 
/* function prototypes */ 
long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 
BOOL FAR PASCAL DialogProcedure (HWND hdlg, unsigned Gaescae; WORD wParam, LONG lParam) ; 


The program’s .DEF definition file must list the dialog box function in the EXPORTS section. 


NAME . generic 

DESCRIPTION "windows enumeration example’ 
.EXETYPE WINDOWS 

STUB "WINSTUB.EXE' 

CODE PRELOAD MOVEABLE 

DATA ; PRELOAD MOVEABLE MULTIPLE 
HEAPSIZE 1024 . 

STACKSIZE 4096" 


EXPORTS WndProc 
DialogProcedure 


The WndProc() and DialogProcedure() functions of the C program are shown in the follow- 
ing example. The WinMain() function is identical to the GENERIC.C function in Chapter 1, Over- 
view of Windows Programming. Note that the two integer values, which can be changed from 
within the dialog box, are defined as global variables. This makes their values available to both - 
the WndProc() function and the DialogProcedure() function. 


© GENERIC.C Excerpt 


int nEditOne = 0 ;. /* global variables */ 
int nEditTwo = 0; ; 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


-PAINTSTRUCT Ps ; 

static FARPROC ipfndDialogProc 7 

char cBuf [128] ; 

switch (iMessage) /* process windows messages */ 


case WM_| PAINT: 
BeginPaint (hWnd, &ps) ; 
Textout (ps.hdc, 10, 10,-cBuf, wsprintf (cBuf, 
“The current values are: 4d, “~d", oe nEditTwo)) ; 
EndPaint Shwnd, &ps) ; 


break ; . 
case WM_ COMMAND: _ /* process menu items */ 
suites (wParam), 
case IDM. DOIT: : /* User hit the “Do it" menu item */ 
“LpfnDialogProc = MakeProcInstance (DialogProcedure, 
ghInstance) ; 
DialogBox (ghInstance, “exmpdlg", hWnd, 
lpfnDialogProc) ; 


FreeProcInstance (LpfnDialogProc) ; 7 
InvalidateRect (hWnd, NULL, TRUE) ; ; /* force paint */ 


break ; 
case IDM_QUIT: /* send end of i aah messagé */ 
DestroyWindow (hWnd) ; _ 
break ; 
} 
. break ; : 
case WM_DESTROY: /* stop application */ .- 


_ PostQuitMessage (0) ; 
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break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


BOOL FAR PASCAL DialogProcedure (HWND hDlg, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


BOOL 


bBool ; 


switch (iMessage) 


case WM_INITDIALOG: 
SetDlgItemInt ChDlg, DLI_EDIT1, nEditOne, TRUE) ; 
SetDlLgIitemInt ChDlg, DLI_LEDIT2, nEditTwo, TRUE) ; 
break ; 
case WM_COMMAND: 
switch (wParam) 
{ 
-case DLI_LEDIT1: 
nEditOne = GetDlgItemInt (hDlg, DLI_LEDIT1, &bBool, TRUE) ; 
return (TRUE) ; 
case DLI_EDIT2: 
TEditTwo = GetDlgItemInt ChDdlg, DLI_LEDIT2, &bBool, TRUE) ; 
return (TRUE) ; 
case DLI_DONE: 
EndDialog ChDlg, NULL) ; 
return (TRUE) ; 
. 
/break ; 
default: 
return (FALSE) ; 
} : 

: return (FALSE) ; 

DiaALoGBoxInpirEcT mWin20 mWin30 mWin3) 

Purpose Creates a modal dialog box. . 

Syntax int DialogBoxIndirect(HANDLE hJnstance, HANDLE a ele lad HWND ANGE arent, 

| . FARPROC lpDialogFunc); 

Description This function is identical to DialogBox(), except that the dialog box resource data is specified by 
a memory handle instead of the resource name. In both cases, the dialog box created is applica- 
tion-modal, meaning that the dialog box window keeps the input focus until it is closed. The focus 
can be switched to another application, but not to another window of the application that called 
DialogBoxIndirect(). 

Uses The dialog box template in memory can be modified to change the dialog box as the application 
runs (called a “dynamic dialog box” ). Typical applications are database programs. See the dis- 

cussion at the beginning of this chapter. Specifying the dialog box resource data indirectly allows 
the program to have more control over when the resource data is loaded and discarded. This can 
be important in applications that use a large number of resources, or in applications when 
, memory or efficiency is critical. 
_ Returns int, the wResult parameter passed within the dialog box function when EndDialog() was called. 
a This value is not normally used. Windows returns—1 if the dialog box could not be created. 
See Also DialogBox(), for a full description of the dialog box function and the related files. See also Dia- 


jotestaracnO and. aati 
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‘Parameters 
hInstance 


hDialogTemplate 


hWndParent 
lpDialogFunc 


hDig 
wMsg 


wParam | 


lParam 


HANDLE: The application’s procedure-instance handle. 

HANDLE: The handle to the dialog box resource data. The dialog box template can be created in 

a global memory block and locked with GlobalLock(). Alternatively, the dialog box can be defined 
‘ as a resource and loaded into memory. This handle to the resource data is obtained with Load- 

Resource(). The LockResource() function must also be called before using DialogBoxIndirect(). 

LockResource() physically causes the resource data to be loaded into memory. 

HWND: The parent window’s handle. 


FARPROC: The procedure-instance address of the dialog box function. Use Herchivelnenre) 
to create this value. The dialog box function must have the following style: 


int FAR PASCAL DialogFunc (HWND hDig, WORD wMsg, WORD wParam, DWORD lParam); 
The name “DialogFunc’” is replaced by the name of the message processing function to use for a 
dialog box. Each dialog box will have a separate “DialogFunc” with a different name. The mean- 
ings of the parameters are as follows. . 

HWND: The handle to the dialog box window. This handle can be sed just like any other window 
handle: to obtain the device context, to change the caption, etc. 


WORD: This is the Windows message being passed to the function. For example, wMsg will ‘dil 
WM_INITDIALOG when the dialog box is first started and the first message is sent to the dialog 
box function. 


WORD: This is the WORD parameter passed with the message. See Chapter 9, Windows Mes- 
sages, for the meaning of the wParam and lParam values for each message. 


DWORD: This is the DWORD parameter passed with the message. 
The dialog box function should return TRUE if the function processes the message, and 


. FALSE if the message is not acted on. The exception is processing a WM_INITDIALOG message. - 


Related Messages 


Example 


tong FAR PASCAL 
{ 


In this case, the function should return TRUE only if the SetFocus() function is not called, FALSE 
if SetFocus() is called. SetFocus() is used to establish which control will have the input focus 
when the dialog box is first made visible. If SetFocus() is not used, the first control in the dialog 
box definition receives the input focus. 


Most Windows messages can be processed by a dialog box. WM_ CREATE i is replaced with 
WM_INITDIALOG for dialog boxes. 


This example is identical to the example under the DialogBox() function description, except for 
the changes needed to use the DialogBoxIndirect() function. Note that LockResource() must be 

' called before using the dialog box resource handle hDialog because the resource is not loaded 
into memory until LockResource() is called. 


WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


_ PAINTSTRUCT ps ; 
static FARPROC LpfnDialogProc ; 
static — char ‘ cBuf C256] ; 
static HANDLE hDialog ; 
switch (CiMessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
“The current values are: “’d, as", nEditOne, 
’ CLPSTR) cEditBuf)) ; 
EndPaint ChWnd, SP5 . 
break ; : . 
case WM_ COMMAND: . /* process menu items */ 
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switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item * 
LpfnDialogProc = MakeProcInstance (DialogProcedure, 
ghIinstance) ; 
hDialog = LoadResource (ghInstance, 
FindResource (ghinstance, “exmpdlg", 
RT_DIALOG)) ; ; 
LockResource (hDialog) ; 
DialogBoxIndirect (ghinstance, hDialog, hWnd, 
LpfnDialogProc) ; 
UnlockResource (hDialog) ; 
FreeResource ChDialog) ; 
FreeProcInstance (lpfnDialogProc) ; 
InvatidateRect ChWnd, NULL, TRUE) ; /* force paint */ 
break ; 


[Other program lines] 


DIALOGBOXxINDIRECTPARA eWin2.0 mWin30 mWin3.1 


Purpose 
Syntax 


Description 


Uses 


Returns 
See Also 


Parameters 
hInstance 
hDialogTemplate 


Creates a modal dialog box, and passes a 32-bit data item to the dialog box as it is created. 


int DialogBoxIndirectParam(HANDLE hInstance, HANDLE nD iatogTompiate, HWND 
hWndParent, FARPROC lpDialogFunc, DWORD dwinitParam); 


This function is identical to DialogBox(), except that the dialog box resource data is specified by 
a memory handle instead of the resource name, and the function passes a 32-bit data item to the . 
dialog procedure when the dialog box is created. 

The dialog box created is application-modal, meaning that the dialog box retains the input 
focus until the dialog box is closed. The focus can be shifted to another application, but no other 
window of the application that called DialogBoxIndirectParam() can gain the focus while the 
dialog box is active. 

The 32-bit data item specified by the dwInitParam parameter is ultimately passed to the 
dialog box function as /Param when the dialog box function receives the WM_INITDIALOG mes- 
sage. Normally, this value is used to pass a memory handle to the data that the dialog box will use 
for edit controls, list boxes, and other controls that the user will be changing. 

‘Because the dialog box definition is loaded from a global memory block, the application can 
change the dialog box definition at run time (called a “dynamic dialog box”). See the discussion 
at the beginning of this chapter on dynamic dialog boxes for details. 


\ 
This is the most sophisticated of the dialog box functions. Indirect loading of the dialog resource 
data provides the opportunity to control when resource data is loaded and discarded, The dialog 


_ box template data in memory can be created or modified as the application runs, allowing the 


dialog box to be dynamic. The 32-bit parameter data allows data to be passed to and from the 
dialog function without resorting to global variables. 


int, the wResult paramgter passed within the cialog box function when EndDialog() was called. 
This value is not normally used. Windows returns —1 if the dialog box could not be created. 


DialogBox() for a full description of the dialog box function and the related files. See also 
DialogBoxParam() and DialogBoxIndirect(). 


HANDLE: The application’s procedure-instance handle. 


HANDLE: The handle to the dialog box resource data. The dialog box definition can bi created in 

a global memory block and locked with GlobalLock(). Alternatively, this handle is obtained with 

LoadResource(). The LockResource() function must also be called before using DialogBoxIndirect(). 
 LockResource() physically causes the resource data to be loaded into memory. | 
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_hWndParent 
lpDialogFune 


dwinitParam 


hDig 


wMsg 


wParam 


AParam | 


Related Messages 


Example 


HWND: The parent window's handle. 


FARPROC: The procedure-instance address of the dialog box function. Use MakeProcInstance() 
to create this value. . 


DWORD: This is a 32-bit data item that is passed to the dialog box funetion as the Param value 


when the WM: INITDIALOG message is processed. Frequently used to pass a handle to a memory 
block containing data that the dialog box function will use and/or modify. The dialog box function 
must have the following style: 

int FAR PASCAL DialogFunc (HWND Dig, WORD wMésg, WORD wParam, DWORD lParam); 
The name “DialogFunc” is replaced by the name of the message processing function to use for a . 
dialog box. Each dialog box will have a separate “DialogFunc’” with a different name. The mean- 
ings of the parameters are as follows. 

HWND: The handle to the dialog box window. This handle can be used just like any other window 
handle: to obtain the device context, to change the caption, etc. 

WORD: This is the Windows message being passed to the function. For example, wMsg will equal 
WM_INITDIALOG when the dialog box is first started and the first message is sent to the dialog 
box function. 

WORD: This is the WORD parameter oe with the message. See Chapter 9, Windows Mes- 
sages, for the meaning of the wParam and lParam values for each message. 


DWORD: This is the DWORD parameter passed with the message. This value will be the same as 


- dwinitParam when the dialog box function processes the WM_INITDIALOG message. . 


The dialog box function should return TRUE if the function processes the message, and 
FALSE if the message is not acted on. The exception is processing a WM_INITDIALOG message. 
In this case, the function should return TRUE only if the SetFocus() function is not called, FALSE 
if SetFocus() is called. SetFocus() is used to establish which control will have the input focus 
when the dialog box is first made visible. If SetFocus() is not used, the first bonicor in the dialog 
box definition receives the input focus. 


Most Windows messages can be processed by a dialog box. WM_CREATE is replaced with 
WM_INITDIALOG for dialog boxes. 


This example runs the same dialog box shown in the DialogBox() function amas In this case, 
the more sophisticated DialogBoxIndirectParam() function is used. This allows the data for the 
dialog box to be passed in a custom data structure called TWODATA. Because the function uses 
“indirect” loading of the dialog box resource, the resource data is specified by a memory handle 
obtained with LoadResource(). 

_ Note in the dialog box procedure that the memory for the TWODATA structure i is locked and 
unlocked before and after each call to SetDigitemInt() and SetDlgItemText(). This is necessary, 
as the address of the TWODATA structure may become invalid when Windows processes mes- 
sages for the dialog box. The dialog box function name “DialogProcedure” must be included in the 
EXPORTS section of the program’s .DEF definition ile. The junction prototype must also be in- 


_. cluded in the program’s header file. 


typedef struct tagTwoData [* this could be defined in the header file */ 
¢ P 


int 
ener 
} TWODATA ; 


nOne ; 
cBuf C128] ; 


pons, FAR PASCAL undProc CHWND hwnd, unsigned iMessage, WORD wParam, LONG neeroe? 
c¢ 


PAINTSTRUCT 
static oo ., 


FARPROC ipfndialogProc 7 
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{ 


static 
static 
static 
TWODATA 


switch (iMessage 
{ 
case WM_ 
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char cBuf €256] ; 


HANDLE hDialog ; 
HANDLE hMem ; 
*ptd ; 


) /* process windows messages */ 


CREATE: /* allocate memory for TWODATA data */ 

hMem = LocalAllLoc-<LMEM_MOVEABLE | LMEM_DISCARDABLE, 
sizeof (TWODATA)) ; 

ptd = (TWODATA *) LocalLock (hMem) ; 

ptd->nOne = 1 > 

Lstrepy (ptd->cBuf, "Hi Mom!") >; « 

LocalUnlock (hMem) ; 

break ; 


case WM_PAINT: /* display current TWODATA contents */ 


BeginPaint ChWnd, &ps) ; 
ptd = (TWODATA *) LocalLock (hMem) ; 
TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
“The current values are: %d, %s", ptd->nOne, 
. CLPSTR) ptd->cBuf)) ; 
LocalUnlock (hMem) ; 
EndPaint (hWnd, &ps) ; 
break ; 


case WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 
case IDM_DOIT: /* run dialog box to edit TWODATA data */ 
LpfnDialogProc = MakeProciInstance (DialogProcedure, 
ghInstance) ; 
hDialog = LoadResource (ghInstance, 


FindResource (ghInstance, “exmpdtg", RT_DIALOG)) ; 


LockResource (hDialog) ; 
DialogBoxIndirectParam (ghInstance, hDialog, 
hWnd, LpfnDialogProc, (DWORD) hMem) ; 

UnlockResource (hDialog) ; 
FreeProcinstance (lpfnDialogProc) ; 
FreeResource (hDialog) ; 
InvalidateRect (hWnd, NULL, TRUE) ; /* force paint */ 
break ; 

case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 

} 

break ; 


case WM_DESTROY: /* stop application */ 


default: 


} 
return (OL) ; 


BOOL 
static 
TWODATA 


LocalFree (hMem) ; 
PostQuitMessage (Q) ; 
break; 
/* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


BOOL FAR PASCAL DialogProcedure (HWND hDlg, unsigned iMessage, WORD wParam, LONG LParam) 


bBool ; 
HANDLE hMem ; 
*ptd ; 


switch (iMessage) : ie 


{ 


case WM_INITDIALOG: 
hMem = LOWORD (lParam) ; /* get mem handle from 32 bit data */ 
ptd = (TWODATA *) LocalLock (hMem) ; 


’SetdlgIt 


emInt ChDlg, DLI_LEDIT1, ptd->nOne, TRUE) ; 
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SetDlgItemText (hDlg, DLI_EDIT2, ptd~>cBuf) ; . 
LocalUnlock (hMem) ; 
return (TRUE) ; 


case WM_COMMAND: 

switch (wParam) 

{ 

case DLI_ EDIT1: on /* get edited integer data */ - ts 
‘ptd = CTWODATA *) LocalLock (hMem) ; 
ptd->nOne = GetD igitemint (hdtg, DLI_EDIT1, &bBool, TRUE) ; 
LocalUnLock ChHem) ; 
return (TRUE) ; 

case DLI_EDITe2: /* get edited string data */ 

- ptd = (TWODATA *) LocalLock (hMem) ; 

= GetDlgItemText (hDlg, DLI_EDIT2, ptd->cBuf, 127) >; 
LocalUnlock ChMem) ; 
return (TRUE) ; 
case DLI_DONE: 
‘EndDialog ChOlg, NULL) ; 
a return (TRUE) ; 
} 
break ; 
default: : 
return (FALSE) ; 
} 
return CFALSE) ; 

; 

DiALocBoxParaM | mWin2.0 mWin30 mWin3.l 

Purpose Creates a modal dialog box, and passes a 32-bit data item to the dialog box as it is created. 

Syntax int DialogBoxParam(HANDLE hJnstance, LPSTR [pTemplateName, HWND hWndParent, 
FARPROC [pDialogFunc, DWORD dwInitParam); . 

Description This function is identical to DialogBox(), except that the function passes a 32-bit data item to the 
dialog procedure when the dialog box is created. The dialog box created is application-modal, 
meaning that the dialog box retains the input focus until the dialog box is closed. The focus can 
be shifted to another application, but no other window of the application that called 
DialogBoxIndirectParam() can gain the focus while the dialog box is active. 

The 32-bit data item specified by the dw/nitParam parameter ends up being passed to the 
dialog box function as (Param when the dialog box function receives the WM_INITDIALOG mes- 
sage. Normally, this value is used to pass a memory handle to the data that the dialog box will be © 
using for edit controls, list boxes, and other controls the user will be changing. 

Uses This is probably the best of the DialogBox() functions for normal dialog boxes. The 32- bit data 
item allows data to be exchanged between the program’s WndProc() function and the dialog box 
function, without using global variables. DialogBoxParam() is simpler to use than Dialog- 
BoxIndirectParam(), in that only the dialog definition name is needed. This function avoids the 
complexity of separately loading the dialog box resource data, but at the expense of not being 
able to modify the dialog box template in memory while the application runs. 

Returns int, the wResult parameter passed within the dialog box function when EndDialog() was called. : 
This value is not normally used. Windows returns —1 if the dialog box could not be created.” 

See Also DialogBox() for a full description of the dialog box function and the related files. See also 

. DialogBoxIndirectParam() and DialogBoxIndirect(). 

Parameters 

hInstance . HANDLE: The application’s procedure-instance handle. 

lpTemplateName . 


LPSTR: A pointer to a character string containing the name of the dialog box definition in the © 
resource script file. a, 
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hWndParent 
lpDialogFunc 


dwinitParam 


hDig 


wMsg 


wParam 


lParam 


Related Messages. 


Example 


{ 
int 
char 

} 


{ 
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HWND: The parent window's handle. 


FARPROC: The procedure-instance address of the dialog box function. Use MakeProcInstance() 
to create this value. 


DWORD: This is a 32-bit data item that is passed to the dialog Bok function as the [Param value 
when the WM_INITDIALOG message is processed. The dialog box function must have the follow- 
ing style: 

int FAR PASCAL DialogFunc (HWND Dig, WORD wMsg, WORD wParam, DWORD lParam); 


The name “DialogFunc” is replaced by the name of the message processing function to use for a 
dialog box. Each dialog box will have a separate “DialogFunc” with a different name. The mean- 
ings of the parameters are as follows. 


HWND: The handle to the dialog box window. This handle can be used just like any other window 
handle: to obtain the device context, to change the caption, etc. 


WORD: This is the Windows message being passed to the function. For example, wMsg will equal 
WM_INITDIALOG when the dialog box is first started and the first message is sent to the dialog 
box function. 


WORD: This is the WORD parameter passed with the message. See Chapter 9, Windows Mes- 
sages, for the meaning of the wParam and lParam values for each message. 


DWORD: This is the DWORD parameter passed with the message. This value will be equal to 
dwinitParam when the WM_INITDIALOG message is processed. 

The dialog box function should return TRUE if the function processes the message, and 
FALSE if the message is not acted on. The exception is processing a WM_INITDIALOG message. 
In this case, the function should return TRUE only if the SetFocus() function is not called, FALSE 
if SetFocus() is called. SetFocus() is used to establish which control will have the input focus 
when the dialog box is first made visible. If SetFocus() is not used, the first control in the dialog 
box definition receives the input focus. 


Most Windows messages can be processed by a dialog box. WM_CREATE is replaced with 
WM_INITDIALOG for dialog boxes. 


This example runs the same dialog box shown in the DialogBox() function example. In this case, 
the more sophisticated DialogBoxParam() function is used. This example allows the data for the 
dialog box to be passed in a custom data structure called TWODATA. The dialog box function 
name “DialogProcedure” must be included in the EXPORTS section of the program’s .DEF defini- 
tion file. The function prototype must also be included in the program's header file. 


typedef struct.tagTwoData /* this definition can go in header file */ 


“nOne ; 
cBuf £128] ; 
TWODATA ; 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


PAINTSTRUCT ps ; 


static 
static 
static 
static 
TWODATA 


FARPROC LpfnDialogProc ; 
char cBuf £256] ; 
HANDLE ‘hDialog ; 
HANDLE hMem ; 

*ptd ; 


switch (CiMessage) /* process windows messages */ 


{ 


case WM_CREATE: /* allocate memory for the TWODATA data */ 
hMem = LocalAlloc (LMEM_MOVEABLE | LMEM_DISCARDABLE, 
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sizeof (TWODATA)) ; 
ptd = (TWODATA *) Wecatleck ChMem) ; 
ptd->n0One = 1; 
Listrepy (ptd->cBuf, "Hi Mom!") ; 
LocalUnLlock ChMem) ; 
break ; 
case WM_PAINT: /* display the current TWODATA contents */ 
BeginPaint ChWnd, &ps) ; 
ptd = (TWODATA *y LocalLock ChMem) ; 
Textout (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
“The current values are: %d, %s", ptdsrndne, 
(LPSTR) ptd->cBuf)) ; 
LocalUnLock ChMem) ; 
EndPaint (hWnd, ceo 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
LpfnDialogProc = MakeProcInstance (DialogProcedure, 
ghiInstance) ; 
DialogBoxParam (ghInstance, “exmpdlg", hWnd, 
LpfnDialogProc, (DWORD) hMem) ; 
FreeProcinstance (lpfnDialogProc) ; 
InvalidateRect (hWnd, NULL, TRUE) ; /* force paint */ 
6 : : break ; 
3 case IDM_QUIT: /* send end of application message */ 
eo * DestroyWindow (hWnd) ; 
oa break ; 
} 
break ; : 
case WM_DESTROY: -: as stop application a 
LocalFree (hMem) ; . 
PostQuitMessage (ay ‘s 
break ; 
- default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


}, $s : 
return (OL) ; 


1OOL FAR PASCAL DialogProcedure CHWND hDlg, unsigned iMessage, WORD wParam, LONG lParam) 


BOOL . — bBool ; | 
Static. HANDLE - J hMem; -. 2 
TWODATA x Seas So *ptd ; 


switch (iMessage) 


- case WM_INITDIALOG: 
: “hMem = LOWORD (LParam) ;° /* get mem handle from 32 bit data */ 

ptd = (CTWODATA *) Leeattock ChMem) ; 
‘SetDlgItemInt (hDlg, DLI_EDIT1, a cazenones TRUE) ; 
SetDlgItemText (hDlg, DLI_EDIT2, ptd->cBuf) ; 
LocalUnlock (hMem) ; 
return (TRUE) ; 

case WM_COMMAND:. : 

" switch (wParam) | 


case DLI_EDIT1: /* edit integer data .*/ 
ptd = (TWODATA *) LocalLock (hMem) ; 
ptd->nOne = GetDlgItemint ChDlg, DLI_EDIT1, 

. &bBool, TRUE) : 

LocatUnlock ChMem) ; 

return (TRUE) ; 

case DLI_LEDIT2: ....  ‘/* edit string data */ 

: -ptd = (TWODATA.*).LocalLock ChMem) ; ‘ 

GetDlgitemText cue DLI ~FOTT2, pta-rebut, 427) . 


— = 


default: 


} 
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LocalUnlock (hMem) ; 
return (TRUE) ; 

case DLI_DONE: 
EndDialog ChDlg, NULL) ; 
return (TRUE) ; 

} 

break ; 


return (FALSE) ; 


return CFALSE) ; 


Example . 


- 
EnpDDIALOG mWin2.0 mWin30 mWin31 
Purpose Closes a modal dialog box and returns control to the calling function. 

Syntax void EndDialog(HWND hDlg, int nResult); 

: Description This function stops and erases modal dialog boxes displayed with the DialogBox() function. 

EndDialog() can be called at any point in the dialog box function. 
Uses This is the only way to properly exit a modal dialog box and return control to the calling function. 
Ifa dialog box is created from within another dialog box function, calling EndDialog() only de- 
letes the dialog box associated with the active dialog box and dialog box function. — 

Returns No returned value (void). 

See Also DialogBox() 

Parameters | 

hDig HWND: The handle of the dialog box window. 

dclas a int: The value to be returned when DialogBox() returns the calling function. 

Example See the example under DialogBox(). 

GETDIALOGBASEUNITS © mm Win2.0) m@Win3.0 mm Win3.1 

Purpose Determines the-size of the dialog base units used to create dialog boxes and position controls. 

Syntax LONG GetDialogBaseUnits(void); 

Description Dialog boxes use measurements based on the size of the font characters. These are called “dialog 

base units~’ The X direction is measured in units of one-fourth of the font width. The Y direction 

_ .is measured in units of one-eighth of the font height. This function allows you to determine the 
size of the font width in use. Note that the returned values are for the entire font bounding. 
; rectangle measured in pixels, not for one-fourth or one-eighth of the size. 

Uses Useful if you want to paint on the dialog box window, but you only know the location of controls as 
measured with dialog box.units. The location of the controls measured in pixels will change on 
different displays with different resolutions. 

Returns LONG. The low-order word contains the width of the dialog box font, measured in phe The. 

-_ high-order word contains the height of the dialog box font, measured in pixels. 

See Also See the discussion of the FONT statement at the beginning of 

; this chapter. 

Parameters _ None (void). 

Related Messages WM _PAINT 

_ This example, as shown in Figure 13-5,-creates a dialog box. 


_.with only one control. The dialog box function processes Figurel9-5. GetDialog- pe 
“ WM_PAINT messages and outputs text dinscty, to the dialog BaseUnits(, ) Example. 
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box window. It also draws a line under the text. The line length is computed to be the number of 
characters times the width of a character, Note that the line ends up longer than the text string, 
as the system font does not use fixed character spacing. To compute the actual Jength of the ° 
string, the program would need to use GetTextExtent(). 

The dialog box definition for the resource file is simple. Because the font is not specified with 
a ‘FONT statement, the system font is used in the dialog box. The dialog control ID DLI_DONE is 
defined in the program’ s header file. 


EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE 10, 18, 128, 66 
STYLE WS_DLGFRAME | WS_POPUP 
BEGIN 
CONTROL “Done", DLI_DONE, "button", 
BS_DEFPUSHBUTTON | WS_TABSTOP | WS_CHILD, 75, 50, 48, 14 
END 


Here is the dialog box function. This function would be called using the DialogBox() function 
and listed in the EXPORTS section of the program’s .DEF definition file... 


BOOL FAR PASCAL DialogProc can hDlg, WORD wMess, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT | psy 
‘Static ' "  Gnt- °° nBasexX, nBaseyY ;° 
LONG is LBaseUnits ; 


switch (wMess) 
{ 


case WM_INITDIALOG: 
\BaseUnits = GetDialogBaseUnits () ; 
nBaseX = LOWORD (lBaseUnits) ; 
nBaseY = RIWORD (LBaseUnits) ; 
‘return TRUE ; 
case WM_PAINT: 
‘ BeginPaint (hola, ieard 
. TextOut (ps.hdc, 0, 0, “Direct. Text Out.", 16) ; 
MoveTo (ps.hdc, 0, nBaseyY) ; 
LineTo (ps.hdc, nBasex * 16, nBaeeN 2:2 
end rant: ChDlg, &ps) ; 
' break ; 
case WM_COMMAND: 
switch (wParam) 
t 


' case DLI_DONE: 
EndDialog (hDlg, 0) ; 
return TRUE ; 


default: 
, return FALSE’; 
: } 
. return FALSE ; 
: oan 
GetDiGCreiID mWin2.0 mWin30 mWin3.1 
Purpose”. Retrieves 4 dialog box control's ID value, given the control’s window handle. 
‘Syntax — int GetDlgCtrlID(HWND hWnd): . 
Description This is the opposite of GetD!gItem(). Given that the program has the window handle of a control, 
a this function will retrieve the control’s ID value. 
Uses Not often used. N ormaliy, you will define all of the ID values in a header file, and use them to send 
: messages to the child window controls. 
Returns. ‘int, the control ID number for the dialog box control that has a hWnd as a window handle: Re- - 


tums NULL if hWnd i is not a valid window handle. The return value is undefined if hWnd is not a 
dialog box control window. - 
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See Also 


Parameters 
hWnd 


Example 
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GetDigltem(), SendDlgItemMessage(). 


HWND: The control ID's window handle. 


This example, which is shown in Figure 13-6, shows several equivalent ways of sending messages 
to dialog box controls. When the WM_INITDIALOG message is received, the dialog box control 
sets the edit control’s text to “First Text.” The handle to the 
edit control’s window is also retrieved. When the DLI_SECOND Text Changes 
button is pressed, the edit text is changed directly by sending a 
message to the edit control window. This technique is equiva- , 
lent to using SetDlgItemText(). When the DLI_THIRD button 
is pressed, the dialog box ID value for the edit control is ob- 
tained from the edit control’s window handle using GetDig- Figure 13-6. GetDlgCtrlID() 
CtrlID(). The ID is then used to change the edit control's text, And GetDigitem() Example. 
again using SetDIgItemText(). 

This example only shows the dialog box procedure for the program. See the example under 


- the DialogBox() function description for related program files. 


BOOL FAR PASCAL DialogProc CHWND hDlg, WORD wMess, WORD wParam, LONG LParam) 


HWND hControl ; 
nEditID ; YS 


switch (wMess) 


{ 
static 
int 
} 
} 
GretTDicGITem 
Purpose 
Syntax 
Description 
Uses | 


case WM_INITDIALOG: 
SetDlgItemText (hDlg,:DLI_EDIT, "First exe : 
hControl = aethlgites ChDlg, DLI_EDIT) ; 
return TRUE ; 
case WM_COMMAND: 
switch (wParam) 


case DLI_SECOND: : 

SendMessage (hControl, WM_SETTEXT, 0, 
(DWORD) ¢LPSTR “Second Text") H 

return TRUE ; - 

case DLI_THIRD: ; 
nEditID = GetDlgCtrlID ChControl) ; 
SetDlgItemText (hDlg, nEditID, "Third Text") ; 
return TRUE ; 

case DLI_DONE: 
‘EndDialog cnDigs 0) ; 
return TRUE ; 

default: 
return FALSE ; 


return FALSE ; 


eWin2.0 mWin3.0 mWin3.1 
Retrieves the window handle for a dialog box control, given the control's ID number. 
HWND GetDlgItem(HWND hWnd, int nJDDigItem); : 


All dialog box controls, such as buttons and list boxes, are child windows. Normally, they are dealt 
with indirectly using a function like SendDlgItemMessage(), which uses the dialog box control 
ID. An alternative is to deal wjth the child windows directly by obtaining the window’s handle. 


The handle of the dialog box control window can be used to change the behavior of the child 
window by subclassing. After the window handle is obtained with GetDlgItem(), the application 
uses SetWindowLong() and CaliWindowProc() to subclass the control. 
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_ Returns ae the window handle for the dialog box control, 

See Also - Get IgCtrlIDQ), SetWindowLong(). The CallWindowProc() function description in Chapter 8, 

= Message Processing Functions, has an example of subclassing a button control. 

Parameters — 

hWnd ; HWND: The dialog ite handle, usually named hDlg. 

nIDDigitem int: The dialog box control ID value. 

Example See the previous example under the GetDlgCtrlID() function description. 

GetDicITemMInr Win2.0 mWin3.0 mWin3.1 

Purpose __ Retrieves an integer value from a control in a dialog box. . 

Syntax WORD GetDigitemInt(HWND hDig, int nJDDigitem, BOOL FAR “IpTranslated, BOOL bSignea); 

Description This is a shortcut method of retrieving an integer value from a control ina dialog box. The func- 
tion is equivalent to using the WM_GETTEXT message to retrieve the character string from the 
control, and then using the atoi() C library function to convert the string to an integer. The text 
characters in the edit control are converted to an integer value starting with the leftmost charac- 
ter. The first nonnumeric character halts the reading process. 

Uses This is the standard way to retrieve an integer value from an edit control. 

Returns The integer value of the text in the edit control. Because zero is a valid integer vatue, errors are 

: reported with the lpTranslated parameter. 

See Also SetDigitemInt(), GetDlgitemText(), SetDigItemText() 

Parameters . 

hDig. HWND: The dialog box handle. 

nIDDigltem int: The dialog box edit control ID. Normally, these values are rr 
defined in a separate header file. Title String Here 


lpTranslated _BOOL FAR *: The location pointed to bypTranslated is setto || [0] tnteger tnput fied 
TRUE if the edit control was properly converted to an integer. | String Input field. 
It is set to FALSE if the value overflowed (unsigned greater 
than 65,535 or signed greater than. 32,767), or if nonnumeric 


characters preceded any digits. Figurele-Z™” 
bSigned ~  BOOL: TRUE if the value to be retrieved is to be asignedinte- GetDigItemInt(), 

ger (int), FALSE if unsigned. GetDigltemText(), 
Related Messages WM_GETTEXT SetDightemInt(), and 


Example _ This example, which is shown in Figure 13-7, uses a dialog box er nlg eel) Peniinle 


to allow editing of two global variables, an integer and a char- 

acter string. The dialog box pops up when the user clicks the “Do It!” menu item. The current 
values are updated into the edit fields of the dialog box with SetDlgItemInt() and SetDlg- 
ItemText(). When the user does any activity involving selection or editing of either edit field, the 
current value is retrieved using GetDigItemInt() and GetDlgltemText(). See the example under 
DialogBox() for details of the other files associated with this example. Only the C source oud’ for 
the WndProc() and a TanCHIONS are shown in this example. 


int nEdi tone =0; 
char cEditBuf £1283 = e"Hi There!"> ; 


Long FAR PASCAL WndProc CHWND hWnd, unadorned er ee WORD wParam, LONG LParam) 
{ 
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‘} 


BOOL FAR PASCAL DialogProcedure CHWND hDlg, 


{ 


PAINTSTRUCT. ps; 

static FARPROC lLpfnDialogProc ; 

char cBuf [256] ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 


"The current values are: 4d, 4s", nEditOne, 


CLPSTR) cEditBuf)) ; 
EndPaint ChWnd, &ps) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_DOIT: /* User hit the “Do it" menu item */. 
LpfnDialogProc = MakeProcInstance (DialogProcedure, 


ghIinstance) ; 


DialogBox (ghInstance, “exmpdlg", hWnd, LpfnDialogProc) ;— 


FreeProcInstance (lpfnDialogProc) ; 


InvalidateRect (hWnd, NULL, TRUE) ; /* force paint */ 


break ; 


case IDM_QUIT: /* send end of application message */ 


DestroyWindow (hWnd) ; 
break ; 
} 
break ; . oe 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 


default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; 


BOOL bBool ; 


switch (iMessage) 
{ 
case WM_INITDIALOG: ; 
SetDlgItemInt (hDlg, DLI_EDIT1, nEditOne, TRUE) ; 
SetDlgItemText (hDlg, DLI_EDIT2, cEditBuf) ; 
break ; 
case WM_COMMAND: 
switch (wParam) 
{ 
case DLI_EDIT1: 
nEditOne = GetDlgItemInt ChDlg, DLI_EDIT1, 
&bBool, TRUE) ; 
return (TRUE) ; 
case DLI_EDIT2: 


GetDlgItemText ChDlg, DLILEDIT2, cEditBuf, 127) ; 


return (TRUE) ; 
case DLI_DONE: 
EndDiatog ChDlg, NULL) ; 
return (TRUE) ; 
3 
break ; 
default: 
return CFALSE) ; 
} 
return (FALSE) ; 
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unsigned iMessage, WORD wParam, LONG LParam) 


WINDOWS API BIBLE 


GETDLGITEMTEXT eWin2.0 mWin3.0 . wWin3l 

Purpose Retrieves a character string from an edit control in a dialog box. 

Syntax int GetDlgItemText(HWND ADig, int nIDDigitem, LPSTR lpString, int nMaxCount); 

Description This is a shortcut method of retrieving the text string froma control ina dialog box. It is equiva- 
lent to sending a WM_GETTEXT message to the control. 

Uses Normally used with edit controls to retrieve the current edited value. 

Returns int, the number of characters copied. | 

See Also GetDlgitemInt(), SetDigItemText(), SetDlgItemInt() 

Parameters 

hDlg HWND: The dialog box handle. 

nIDDigitem _ int: The dialog box edit control ID. Normally, these values are defined in a separate header file. 

lpString LPSTR: A pointer to a buffer that: holds the character string. It must be at least nMaxCount 
characters wide. . 

nMaxCount ‘int: The maximum number of characters to copy into the buffer pointed to by lpString. 

Related Messages WM_GETTEXT. 

Example See the previous example under the GetDigltemint() function description. 


GETNEXTDLGGRovuPITEM 


Purpose 


Syntax 
Description 


Uses 
Returns 
See Also 
Parameters 
hDlg 

hCtl 


bPrevious 


Example 


Win 2.0 Win 3.0 Win 3.1 
Finds the next (or previous) window handle of the dialog box control, within a group of controls, 


_ that will receive the input focus if the user presses one of the arrow keys. 


HWND GetNextDigGroupItem(HWND Dig, HWND hCil, BOOL bPrevious); 


Dialog box controls can be placed in groups by starting each group with an item with the . 
WS_GROUP style. The group continues until the next WS_GROUP styled item is encountered. 
The user can move between items of a group by pressing the arrow keys. The GetNextDlg- 
GroupItem() returns the handle of the control that will be highlighted next within the group. 


Used in building keyboard interfaces for dialog boxes. 
HWND, the handle of the next or previous dialog box control of the group. 
GetDigItem(), GetNextDlgTabItem() 


HWND: The handle of the dialog box windows. 


HWND: The handle of the dialog box control to start from. Retrieve this handle with GetDlg- 
Item(). 


BOOL: Set to TRUE to find the previous control in the group. This is the item that will have the input 
focus if the user presses the left or down arrow key. Set to FALSE to find the next control in the 
group. This is the item that will have the input focus if the user presses the right or up arrow key. 


The example illustrated in Figure 13-8 shows a dialog box with - 
four check boxes and a pushbutton. When the dialog box starts, 
the check box in the upper left has the input focus. The dialog 
box function processes the WM_INITDIALOG message and. 
changes the names of the controls for the button with the in- 
put focus, the next group button (the button that will receive 
the input focus if the right arrow key is pressed), andthe next Figurel3-8. GetNextDlg- 


(Next Tab 


CONext Group O4 


tab button (the button that will receive the input focus ifthe Groupltem() and GetNext- 


tab key is pressed). DigTabltem() Example. 
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Note in the dialog box definition that the WS_TABSTOF flags are placed at each location 
where the cursor should jump to if the tab key is pressed. The WS_GROUP flags are placed at the 
start of each group, and continue until the next WS_GROUP flag. These control the reaction to 
pressing the arrow keys. 


EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE 10, 18, 145, 80 
STYLE WS_DLGFRAME | WS_VISIBLE | WS_POPUP 
BEGIN 
CONTROL “", DLI_CHECK1, "button", 
BS_CHECKBOX | WS_TABSTOP | WS GROUP | WS_CHILD, 12, 20, 48,712 
CONTROL “", DLI-CHECK2, “kutton", 
BS_CHECKBOX | WS_CHILD, 12, 39, 48, 12 
CONTROL “", DLI_CHECK3, “button", 
_ BS_CHECKBOX | WS_TABSTOP | WS_GROUP | WS_CHILD, 84, 21, 45, 12 
CONTROL “", DLI_CHECK4, “button”, 
BS_CHECKBOX | WS_CHILD, 84, 39, 45, 12 
CONTROL "Done", DLI_DONE, “button", 
BS_DEFPUSHBUTTON | WS_TABSTOP | WS_CHILD, 45, 66, 48, 12 
END 


This listing only shows the dialog box function for the program. The remainder of the pro- 
gram is identical to the CreateDialog() example. 


BOOL FAR PASCAL DialogProc (CHWND hDlg, WORD wMess, WORD wParam, LONG lParam) 
{ 


HWND hControl, hFirstGroup s 


switch (wMess) 
{ 
case WM_INITDIALOG: 
SetDlgItemText (hDlg, DLI_CHECK1, "1") ; 
SetDlgItemText (hDlg, DLI_CHECK2, “2") ; 
SetDlgItemText (hDlg, DLI_CHECK3, "3") ; 
SetDlgItemText (hDlg, DLI_CHECK4, "4") ; 
hFirstGroup = GetDlgItem (hDlg, DLI_CHECK1) ; 
SendMessage (hFirstGroup, WM_SETTEXT, 0, 
CDWORD)CLPSTR) “Focus here") ; 
hControl = GetNextDlgGroupitem (hDlg, hFirstGroup, 
FALSE) ; 
SendMessage C(hControl, WM_SETTEXT, 0, 
CDWORD)C(LPSTR) “Next Group") ; 
hControl = GetNextDlgTabItem (hDlg, hFirstGroup, 
FALSE) ; 
SendMessage (hControl, WM_SETTEXT, OQ, 
CDWORD)CLPSTR) "Next Tab") ; 
return TRUE ; 
case WM_COMMAND: /* there is only one command —- quits */ 
switch (wParam) 
case DLI_DONE: 
EndDialog (hDlg, 0) ; 
hDLgBox = NULL ; 
return TRUE ; 
} 
} 
return FALSE ; 
} 
GETNEXTDiLGTaBITEM Win 2.0 Win 3.0 mWin3.1 
Purpose Finds the next (or previous) window handle of the dialog box control that will receive the input 
focus if the user presses the key. 
Syntax HWND GetNextDlgTabItem(HWND hDig, HWND hCtl, BOOL bPrevious); 
Description A keyboard shortcut for moving between dialog box controls can be obtained by placing 


WS_TABSTOP styles in the definition of each item that the tab key should stop on. Pressing the 
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Uses Used in building keyboard interfaces for dialog boxes. 

Returns HWND, the handle of the next or previous dialog box control that will be selected if the (vas) key 
is used. 

See Also GetDlgItem(), GetNextDlgGroupItem() 

Parameters 

hDig HWND: The handle of the dialog box windows. 

hCil HWND: The handle of the dialog box control from which to start. Retrieve this handle with 
GetDigItem(). 

bPrevious BOOL: Set to TRUE to find the previous WS_TABSTOP sentiolt in the dialog box. This is the item 
that will have the input focus if the user presses GuiFt)-(tas). Set to FALSE to find the next 
WS_TABSTOP control. This is the item that will have the input focus if the user presses (tas). 

Example See the previous example under GetNextDlgGrouplItem(). 

IsD1ALOGMESSAGE eWin2.0 mWin30 mWin3.l 

Purpose Determines whether a message is meant for a dialog box. If so, keyboard translations are per- 

. formed, and the message is passed to the dialog box function. 

Syntax BOOL IsDialogMessage(HWND hDig, LPMSG lpMsqg); 

Description Modeless dialog boxes can remain on the screen for the duration of the program. During this 
period, the message loop must determine whether to send the message to the WndProc() func- 
tion, or to the dialog box function(s). In addition to diverting messages to the dialog box function, 
IsDialogMessage() converts some keypress messages. For example, the (vas) key is interpreted to 
move the input focus to the next control with the WS_TABSTOP message. DispatchMessage() 
will also send messages to the dialog box function, but without the character translations. 

Uses Necessary in the message loop for all applications containing modeless dialog boxes that use a 
keyboard interface. 

Returns BOOL. TRUE if the message was processed and sent to the dialog box function, FALSE if not. If 

. FALSE is returned, the message should be passed to the TranslateMessage() and Dispatch- 
Message() fimetions. 

See Also GetMessage(), CreateDialog() 

Parameters 

hDlg HWND: The dialog box handle. This value is returned by CreateDialog() and the other 
CreateDialog functions. The value should be stored in a global variable to make it available tothe — 
message loop within WinMain(). Set hDig to zero before and after Me modeless dialog box is 
active. 

lpMsg LPMSG: A pointer Y the MSG structure retrieved from Windows m Gcac or Peek- 
Message(). 

' This listing shows a typical message loop for an application with one or more a inedeless dialog 


Example 


/ 


: key moves to the next item with the WS_TABSTOP style. Pressing (SHFT)-(ias) moves in the 


opposite direction. GetNextDlgTabItem() returns the handle of the control that will be high- 
lighted next if the key is used. 


boxes. The TranslateMessage() and DispatchMessage() functions only process the message if the 
dialog box is not currently active or if the message is not for a dialog box, See CremsDialoey) for 


"amore complete listing. 


while (GetMessage (&msg, NULL, 0, 0)) 
{ < Z 


4 ChDLgModeless == NULL J] 90° 


602. 


} 


13. DIALOG BOXES Vv 


!'IsDialogMessage (hDlgModeless, &msg)) 


TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} 


return msg.wParam ; 


IsDLGBuTTONCHECKED wWin2.0 mWin3.0 mWin3.1 
Purpose 


Determines whether a check box or radio button control is checked, or whether a three-state 
button control is checked or grayed. 


Syntax WORD IsDlgButtonChecked(HWND hDig, int nJDButton); 

Description Radio buttons and check boxes can be checked or unchecked. Three-state buttons can be 
checked or grayed. IsDlgButtonChecked() determines the current state of a dialog box control. 

Uses Normally used with the AUTO button styles that automatically change from unchecked to 
checked, etc. 

Returns WORD, the current checked state. 0 for unchecked, 1 for checked, 2 for grayed (if the control is a 
three-state radio button or check box). 

See Also CheckDIgButton(), CheckRadioButton() 

Parameters 

hDlg HWND: The dialog box window handle. 

nIDButton int: The dialog box centrol ID number for the check box or radio button. 

Related Messages BM_SETCHECK, BM_GETCHECK 

Example This example uses AUTO button styles to accomplish the same logic as demonstrated in the ex- 


ample under the CreateDialog() function description. The dialog box template is modified to use 
the AUTO button styles. 


EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE 10, 18, 139, 75 

CAPTION “Example Dialog Box" \ 
FONT 10, “Helv” 

STYLE WS_BORDER | WS_CAPTION | WS_DLGFRAME | WS_POPUP | WS_VISIBLE 


BEG 


IN 
CONTROL 


CONTROL 
CONTROL 
CONTROL 
CONTROL 
CONTROL 


CONTROL 


“Title String Here", -1, "static", 
SS_CENTER | WS_CHILD, 27, 6, 78, 9 
“Check box control.", -1, "static", 
SS_LEFT | WS_CHILD, 60, 22, 67, 9 
“Radio buttons.", -1, "static", 
SS_LEFT | WS_CHILD, 60, 39, 73, 10 
“DONE", DLI_DONE, "button", 
BS_DEFPUSHBUTTON | WS_TABSTOP | WS_CHILD, 72, 59, 36, 12 
“ue DLI_CHECKBOX, "button", 
BS_AUTOCHECKBOX | WS_TABSTOP | WS_CHILD, 7, 24, 16, 9 
“First", DLI_RADIO1, “button”, 
BS_AUTORADIOBUTTON | WS_TABSTOP | WS_CHILD, 6, 36, 28, 12 
"Second", DLI_RADIO2, "button", 
BS_AUTORADIOBUTTON | WS_TABSTOP | WS_CHILD, 6, 47, 44, 12 


The dialog box function is modified to take advantage of the automatic checking of both the 
check box and radio buttons. The global variables are updated when the dialog box is closed. The 
- remainder of the program files are-identical to the example shown under CreateDialog(). 


BOOL FAR PASCAL DialogProcedure CHWND hDLg, unsigned iMessage, WORD wParam, LONG LParam) 
{ ; . 


BOOL: bBool ; 
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switch (CiMessage) 


{ 


case WM_ 


case WM_| 


default: 


} 


INITDIALOG: 
if (nCheckOne) 
CheckRadioButton ChDlg, DLI_RADIO1, DLI RADIOS? 
DLI_RADIO1) ; 
if (nRadioOne) 
CheckRadioButton chblg, DLI_RADIO1, DLI —RADI02, 
DLI_RADIO2) ; 
else | 
CheckRadioButton ChDlg, DLI_RADIO1, DLT. _RADIO2, 
DLI_RADIO1) ; 
return (TRUE) ; 
COMMAND: 
switch (wParam) 
C 


case DLI _CHECKBOX: 
if (IsDl gButtonChecked ChDlg, DLI_CHECKBOX)) 
‘CheckDlgButton ChDlg, DLI_CHECKBOX, MF_CHECKED) ; 
else 


CheckDLgButton ChDlg, DLI_CHECKBOX, MF_UNCHECKED) ? 


return (TRUE) ; 
case DLI_RADIO1: 
case DLI_RADIO2: 
if (IsDlLgButtonChecked (hDla, DLI_RADIO1)) 
CheckRadioButton (hDlg, DLI_RADIO1, DLI_RADIO2, 
DLI_RADIO1) ; 
else 
CheckRadioButton ChDlg, DLI _RADIO1, DLI_RADI0O2, 
= DLI_RADIO2) ; 
return (TRUE) ; 
case DLI_DONE: 
nCheckOne = IsDlgButtonChecked C(hDlg, 
DLI_CHECKBOX) ; 
nRadioOne = TeBtgeutrenenecsed ChDlg, 

; DLI_RADIO2) ; 
DestroyWindow (hDlg) ; 
hDlgModeless = 0 ; 
return (TRUE) ; 

} . 
break ; 


return (FALSE) ; 


return (FALSE) ; 


} 


MarDiALoGREctT mWin2.0 wm Win3.0 


Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
hDig 


Converts from dialog base units to screen units (pixels). 
void MapDialogRect(HWND hDig, LPRECT /pRect); 


Win 3.1 


In the dialog box template file, dimensions are given in dialog base units. These are one-fourth of 
a character width for X coordinates and one-eighth of a character height for Y coordinates. 
MapDialogRect() converts a rectangle from these units to screen units. The screen dimensions 


are relative to the upper left corner of the dialog box windows. 


This is a convenient way to determine the size of a dialog box control. All controls are rectangular 


child windows. 


No returned value (void). 
ScreenToClient(), ClientToScreen() 


HWND: The dialog box window handle. 
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lpRect LPRECT: A pointer to a RECT data structure containing the 
rectangle’s dimensions in dialog base units. After MapDialog- 
Rect() is called, the RECT data will contain the same rectangle 

converted to screen units, 


Related Messages WM_SIZE 


Example This example, which is shown in Figure 13-9, movesachildwin- Figurel3-9. MapDialog- 
dow control when either the “I Move” or “Move It” pushbutton Rect() Example. 
controls are clicked with the mouse. 
The dialog box template defines three pushbuttons. The third pushbutton is the one that will 
be moved. Note that the sizes are given in dialog units. 


EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE 10, 18, 128, 66 
STYLE WS_DLGFRAME | WS_POPUP 
BEGIN 
CONTROL "Done", DLI_DONE, "button", 
BS_DEFPUSHBUTTON | WS_TABSTOP | WS_CHILD, 75, 50, 48, 14 
CONTROL “Move It", DLI_LMOVEIT, "button", 
BS_PUSHBUTTON | WS_TABSTOP }{ WS_CHILD, 75, 9, 48, 12 
CONTROL "I Move", DLI_MOVED, “button", 


BS_PUSHBUTTON | WS_TABSTOP | WS_CHILD, 9, 9, 45, 12 
END 


The dialog box function takes the size of the third pushbutton and converts it to a RECT data 
structure. MapDialogRect() then converts the RECT data from dialog units to screen units (pix- 
els). This is an ideal way to move the pushbutton using the MoveWindow() function. 


BOOL FAR PASCAL DialogProc CHWND hDlg, WORD wMess, WORD wParam, LONG lParam) 
{ 


RECT rRect ; 
HWND hControl ; 
static BOOL bToggte = 1; 


switch (wMess) 


case WM_COMMAND: 
switch (wParam) 


{ 
case DLI_MOVED: 
case DLI_MOVEIT: 
SetRect (&rRect, 9, 9, 45 +9, 12+9) ; 
MapDialogRect (hDlg, &rRect) ; 
if (bToggle) 
{ . 
OffsetRect (&rRect, 35, 35) ; 
bToggle =O ; 
}- 
else 
bToggle = 1; 
hControl = GetDlgItem (hDlg, DLI_MOVED) ; 
MoveWindow ChControl, rRect.left, rRect.top, 
rRect.right - rRect.left, 
rRect.bottom —- rRect.top, TRUE) ; 
return TRUE ; 
case DLI_DONE: 
EndDialog (hDlg, 0) ; 
return TRUE ; 
default: 
return FALSE ; 
} 


} 
return FALSE ; 
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MEssaGEBox 
- Purpose 

Syntax | 

Description 


Uses 


Returns 


~ Creates and displays a small window containing a message. 


mWin2.0 mWin30 mWin3l 


int MessageBox(HWND hWndParent, LPSTR lpText, LPSTR lpCaption, WORD wType); 


-MessageBox() is one of the most useful functions in Windows. A simple function call provides a 


complete dialog box, including a limited selection of buttons and icons. The window is automati- 
cally sized. 


Most often used for error and warning messages. Also useful asa placeholder in program develop- 
ment. You can put message boxes in for menu items that have not yet been developed, etc. 


int, the button that was pressed to exit the message box. This can be any of the values listed in 
Table 13-2. 


IDABORT 


An “Abort” button was pressed. 

IDCANCEL A “Cancel” button was pressed. 
_ IDIGNORE . -_ An “Ignore” button was pressed. . ” 

IDNO A “No” button was pressed. -_ 

IDOK An “OK” button was pressed. 

IDRETRY A “Retry” button was pressed. 

IDYES A-“Yes” button was pressed. - . 
Table 13-2. Message Box Returned Values. “ 
See Also MessageBeep(), PEO 
Parameters 
hWndParent HWND: The handle of the parent window. This can be a main window, child window, or dialog box 

a handle. . : 
lpText LPSTR: A pointer to a character string to be placed in the center of the message box. 
lpCaption -LPSTR: A pointer to a character string to be placed i in the caption bar at the as of the message 
sa box. 

wType 


WORD: One or more of the values in Table 13-3, combined with the C isapiiee OR operator (0. 


MB_ABORTRETRYIGNORE The message box contains three buttons: (Abort,) (Retry,) and (Ignore). 
MB_APPLMODAL 


MB_DEFBUTTON1 


BM_DEFBUTTON2 
BM_DEFBUTTON3 


MB_ICONASTERISK 


The message box is application-modal. The user must click one of the message box buttons 
before any other part of the DUO will respond. The user can switch to another program, 
and then return. 


The first pushbutton is the default. The default button is the one that will be activated if the user 
presses the return key. The first button is the default button, unless one of the following two 
styles is used. 


The second button is the default button. 
The third button is the default button. 
An icon with a lowercase “i” in a circle is displayed in the nessage box. 


. MB_ICONEXCLAMATION An icon containing an exclamation point is displayed in the message box. 


MB_ICONHAND 


An icon with a hand (stop symbol) is displayed in the message box. 
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MB_ICONINFORMATION An icon with a lowercase “i” in a circle is displayed in the message box. 


MB_ICONQUESTION Anicon containing a question mark is displayed in the message box. 

MB_ICONSTOP An icon containing a stop sign is displayed in the message box. This is normally reserved for 
drastic situations. 

MB_OK The message box contains one pushbutton: “OK”. 

MB_OKCANCEL The message box contains two pushbuttons: “OK” and “Cancel.” 

MB_RETRYCANCEL The message box contains two pushbuttons: “Retry” and “Cancel.”. 

MB_SYSTEMMODAL The message box is system-modal. No other program can gain the input focus until a button in 


the message box is clicked. If the MB_ICONHAND style is used with this style, Windows 
messages are immediately stopped to all applications. 


MB_TASKMODAL Similar to MB_LAPPLMODAL. With this style, hWndParent can be set to NULL. This causes all 
child windows of the parent to be disabled until a pushbutton on the message box window is 
clicked. 

MB_YESNO The message box contains two buttons: “Yes” and “No.” 

MB_YESNOCANCEL The message box contains three buttons: “Yes,” “No,” and “Cancel.” - 


Table 13-3. Message Box Flags. 


Message Box 


Example This example displays a message box when the user clicks the 
“Do It!” menu item. The appearance of the message box is QD) ths tesssge oF Lite Vatue 
shown in Figure 13-10. The MessageBox() returns an integer 


value that specifies which button was clicked to exit the mes- 
sage box. In this case, the result is displayed on the main Figure 13-10. MessageBox() 
window's client area after the message box disappears. Example. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ hs 


int nReturned ; 
HOC hoc ; 
switch (iMessage) /* process windows messages */ 
{ > ; ; 
case WM_COMMAND:  '  /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 


nReturned = = MessageBox ChWnd, 

“This Message is Of Little Value”, 

' "Message Box" 

MB ICONEXCLAMATION | MB_OKCANCEL) ; 
hDC = GetDC ChWnd) ; 
if (nReturned == IDCANCEL) 

TextOut (hDC, 10, 10, "Returned Cancel.", 16) ; 
else 

TextOut (hDC, 10, 10, “Returned OK.", 12) ;. 
ReleaseDC (hWnd, hDC) ; 


break ; 
[Other program lines] 
_ SENDDLGITEMMESSAGE | mWin2.0 mWin3d.0 mWin31 
Purpose Sends a message to a dialog box control. 
Syntax -DWORD SendDlgltemMessage(HWND Dig int a eg WORD wMsg, WORD wParam, — 
7 LONG /Param); 
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Description This 1s a Shortcut method for sending a message to a dialog box control. It is equivalent to calling 
GetDlgItem() to obtain the control’s handle, and then using SendMessage() to send the message. 
Like SendMessage(), SendDigItemMessage() sends the message directly to the dialog box func- 

tion, bypassing the message queue. 


~ Uses Used to send nonroutine messages to dialog box controls. The rice activities, such as setting 
the text in a control, are covered by functions like SetDlgItemText(). Less common activities, 
such as adding items to a list box control, are best handled with SendDlgIltemMessage(). 


Returns DWORD, the value returned after the control processed the message. See the message descrip-: 
tion in Chapter 8, Message Processing Functions, to determine the meaning of this value for a 
specific message. 


See Also SendMessage(), GetDlgItem() : 

Parameters 

hDlg HWND: The dialog box window handle (not the handle of the control). 

nIDDigItem WORD: The ID value of the control that will receive the message. 

wMsg _ WORD: The message that the control will receive. 

wParam WORD: The WORD length data sent with the message. See Chapter 9, Windows Messages, for the 
meaning of wParam and lParam for a specific message. 

lParam DWORD: The DWORD length (82-bit) data sent with the message. 


Related Messages All messages can be sent with this function. 


Example This example shows a dialog box with an edit control and scroll 
bar. (See Figure 13-11.) SendDlgItemMessage() is used to send 
an EM_LIMITTEXT message to the edit control when the dia- 
log box starts, limiting input to three digits. The example is 
interesting in that the edit contro] and scroll bar interact. 
Changing the scroll bar position changes the number inthe Figurel3-11. SendDlg- 
edit control. Manually editing the number in the edit control JtemMessage() Example. 
changes ti ¢ scroll bar position. This is an excellent way to pro- 
vide user input for integers. Note in the program logic that no action is taken if the number has 
not changed. This is critical to avoid having infinite loops of messages sent to the dialog box 
function. 


Integer Value 0 - 100 


EXMPDLG DIALOG LOADONCALL MOVEABLE DISCARDABLE 9, 18, 126, 57 
STYLE WS_DLGFRAME | WS_POPUP 
BEGIN 
CONTROL "", DLI_SCROLL, "scrollbar", 
SBS_VERT | WS_CHILD, 102, 6, 9, 45- 
CONTROL “", DLI_EDIT, "edit", 
; ES_LEFT | HS BORDER: ! bees {| WS_CHILD, 9, 18, 36, 12 
CONTROL “Integer Value 0 - 100", "static", 
SS_LEFT | Ws _CHILD, oe 6, 75, 12 
CONTROL "Done", DLI_DONE, “button”, 
BS_ PUSHBUTTON | WS_TABSTOP {| WS_CHILD, 9, 39, 60, 12 
END ' 


Only the dialog box function is shown in the listing. See DialogBox() for other related files 
and commands. 


BOOL FAR.PASCAL DialogProc CHWND hdtg, WORD wSSSy WORD wParam, LONG param) 
{ 


static HWND hSeretl 

int nint ; 
static int ' nOldInt =O; 
BOOL : bBool ; 
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c 2 | 

case WM_INITDIALOG: 
hScroll = GetDlgIitem (hDlg, DLI_SCROLL) ; 

- SetScrollRange (hScrolt, SB_CTL, 0, 100, FALSE) ; 
SetScrollPos (hScroll, SB_CTL, 100, TRUE) ; 
SetDlgItemInt (hDlg, DLI_EDIT, 0, TRUE) ; 
SendDlgItemMessage (hDlg, DLI_LEDIT, EM_LIMITTEXT, 

3, OL) ; 
return TRUE ; 

case WM_VSCROLL: : a 
nInt = nOldInt ; 
switch (wParam) 

{ 
case SB_LINEUP: 
nint += 1; 
break ; 
case $B_PAGEUP: 
nint += 10 ; 
break ; 
case SB_LINEDOWN: 
nint -=1; 
break ; 
case. SB_PAGEDOWN: 
nint -= 10 ; 
break ; 
case SB_THUMBPOSITION: 
nint = 100 -— LOWORD (lParam) ; 
: break ; 
} 
- nInt = min (100, max (0, nInt)) ; 
if (nInt != nOldInt) 
a 
nOldInt = nInt ; 
SetScrollPos (hScroll, SB_CTL, 100 - nOldInt, TRUE) ; 
,SetDlgItemInt (hDlg, DLI_EDIT, nOldiInt, TRUE) ; 
} 
return TRUE ; : 
case WM_COMNAND: /* there is only one command - quits */ 
switch (wParam) 
{ 
case OLI_EDIT: . ; 
nInt = GetDlgItemInt (hDlg, DLI_EDIT, &bBool, 
TRUE) ; 
if (nInt != nOldInt) ‘ 
{ 
nOkdInt = min (100, max (0, nInt)) ; 
SetScro!lPos ChScroll, SB_CTL, 
100 - nOldint, TRUE) . 
} 
return TRUE ; 
case DLI_DONE: : 
EndDialog ChDig, QO) ; 
return TRUE ; ~ 
} 
return TRUE ; 
case WM_DESTROY: 
EndDialog ChDlg, 0?) ; . 
: return: TRUE ; 
’ return FALSE ; 
3. a 
SETDiGITEMINT. | i GWin2.0 m8Win30 -aWin3.1 
Purpose Changes the text in a dialog box control to an integer value. 


Syntax void SetDigltemInt(HWND hDip, int x/DDigitem, WORD wValue, BOOL bSigned); 
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| Description 


- hDig 


This is a shortcut method of changing the text in a control (usually an edit control) to an integer 
value. It is equivalent to sending the WM_SETTEXT message to the control. 

Uses Normally used to change edit control values. | 

Returns No returned value (void). 

See Also — GetDigltemIntQ), SetDigItemText(), GetDigItemText() 

Parameters 

hDlg HWND: The field box handle. 

nIDDIgItem int: The dialog box control ID. Normally, these values are defined in a separate header file. 

wValue WORD: The integer vaiue to be set as text in the control. 

bSigned ~ BOOL: TRUE if the integer is a signed value (int), FALSE if unsigned. 

Related Messages WM_SETTEXT 

_ Example See the example under GetDigItemInt(). 

SETDLGITEMTEXT . EI Win 2.0 Win 3.0 mWin3.1 

Parpose Changes the text in a dialog box control. 

Syntax void SetDlgItemText(HWND hDig, int nIDDigltem, LPSTR ipString); 

Description This is a shortcut function for setting the text in one of the controls of a dialog box. It is equiva- 
lent to sending the WM_SETTEXT message. 

Uses Normally used to change the text in edit controls. 

Returns No returned value (void). 

See Also GetDigltemText(), SetDlgitemInt(), GetDlgItemInt() 

Parameters . 

HWND: The dialog box handle. 

nIDDigitem int: The dialog box control ID. Normally, these values are defined in a separate header file. 

lpString LPSTR: A pointer to a null- terminated string containing the characters to be inserted into the 
dialog box control. 7 

Related Messages WM_SETTEXT x 

Example 


See the example under GetDigItemInt(). 
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Most programmers are apprehensive when they first find out that Windows moves objects around in memory while 
programs are running. This is completely different from programming in a conventional environment like MS-DOS, 
where memory objects stay fixed until deleted. 

Windows provides ample support for managing moveable memory. Using memory blocks under Windows boils 
down to following a few simple rules. Once these rules are understood, memory management becomes no more com- 
plex under Windows, than in environments like MS-DOS Windows provides the programmer with complete control 
over the way memory is used. Most applications do not take advantage of all of these features, but they are worth, 


_ knowing about. This chapter discusses 


Local and Global Memory 


There are two basic kinds of memory under Windows: local memory and global 


Memory organizaton under Windows. 

Allocating memory blocks. 

Using automatic variables. 

Controlling the program’s use of memory with the .DEF definition file. 
How C compiler memory models affect memory use. 

Starting and stopping other programs from within an application. 


Static Data 


- Task Heade 


_ Memory. A program can take advantage of either type of memory, depending on its " Rigure 14-1. The Automatic 
needs, Every program has a private local memory block called the “automatic data Data Segment Organization. 


f 


_~ segment.” The starting size of this area is defined in the program’s .DEF definition 


file, although it can be changed as the program runs. The organization of an application’s automatic data segment is 
shown in Figure 14-1. The maximum size of the segment is limited to-64K.-The first section is the task header, a fixed 
16 bytes of information that Windows uses. Above that is any static data. Static data is the collection of data, such as 
strings you define in the program. 


_ char cBuff€] = "This is a static data string." ; /* static data */ 


Other examples of static data are global variables declared outside of a function definition, and variables within 
a function whose declarations are prefixed by the word “static.” 


static int 1 Oe ee /* static variables */ 


Above the static data is the program’s stack. The C language stores automatic variables (variables declared within 
a function and without the “static” prefix) in the stack. The stack size is also set in the program’s ‘DEF file, with a 
minimum size of 5,120 bytes. The local heap is at the top of the automatic data segment. 

The local heap i is the area where programs can allocate blocks of local memory for their own purposes, and then 
free the blocks when they are no longer needed. If you are familiar with | programming under MS-DOS, you can think of 
the local heap as similar to the memory area allocated using the C function malloc(). This analogy does not go too far, 
as we will soon see. 
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The other kind of memory available to Windows applications is the global heap. This is ine rest of the: memory on 
the system. Windows programs typically use the global heap for large blocks of memory (over 256 bytes as a rule of 
thumb). The local heap is used for smaller blocks, or blocks that will only be used for a short period of time. Again 
making an analogy to MS-DOS programming, the global memory area is something like the area accessed by 

_f{malloc(). 


Segments and Offsets po Sy eee ih tonic edie aR 
Windows uses two types of memory allocation. The two "Figure t ihe Windows 32. Bit Address (LESTE) Values. 
types relate to the architecture of the CPUs (Central 
Processing Unit) on the computers on which Windows programs run. The 8086 through 80486 chips access memory 
using two 16-bit values. These values are called the “segment” and the “offset.” Windows stores full addresses as 32-bit 
values consisting of both the segment and offset, as shown in Figure 14-2. These are “long pointers.” A typical long 
pointer is the memory address of a string. Using conventional C notation, this would be a far pointer to a character 


char far-*cp ; | 


These data types are so common that Windows defines an abbreviation in WINDOWS.H as LPSTR (long pointer to 
a string). In some functions, you will also pass a long address as a double-word (82-bit) value, abbreviated DWORD. 
Both values are 32 bits long. . 


> DWORD and LPSTR Definitions in WINDOWS.H - 
typedef unsignedlong DWORD; 
typedef char .. far *LPSTR; 
In either case, the segment and offset are stored within the 32-bit value as a far address. . orks 

_ For accessing values within an memory area limited to 64K, the segment value does not have to ‘chanes. All of the 
memory locations within the 64K region can be addressed by changing the efiset. This ability makes it possible to 
~ access memory more quickly, as only 16 bits have to be changed, not the full 32 bits. These are called NEAR addresses. 
The typdefs within WINDOWS.H for these 16-bit data types are as follows. 


@® PSTR and WORD Definitions in WINDOWS.H 
typedef char near : *PSTR; 


, typedef unsigned int WORD; 


When you use automatic variables, their values are on the stack. The stack is part of the automatic data snuiek : 
. 80 they are near memory values with 16-bit addresses. When you allocate memory in the local heap, the addresses are 
also 16-bit values. Only global memory objects use the full ita memory addressing. 


Allocating Memory in the Local Heap 

As an example, let’s set aside some memory in the local heap (the top part of the automatic data scerncii) for storing 
up to 128 characters. We will put the string “Hi there!” into the block using the C library function strepy(). The bare- 
bones Windows code for this is ae 


static HANDLE hMem ; 
PSTR .pStr ; 


hem = LocalAlloc (LMEM_MOVEABLE, 128) ; 
pStr = LocalLock (hMem) ; : 

strcpy (pStr, "Hi rnerey 2 ; 

LocalUnlock (hMem) ; ~ 


(Note that Windows has a version of strepy() called “Istrcpy().” It is preferable to using strepy(), a8 it is stored i in 
a DLL and does not add to the size of a application. Istrepy() and related functions are covered in Shapes 19, 
Character Sets and Strings.) 

The LocalAlloc() function reserves 128 bytes of memory in the local heap. The memory is allocated with the 
LMEM_MOVEABLE attribute, meaning that Windows can move this block when it needs to make room for other 
memory objects. Note that the returned value is saved in a static variable, hMem. This is the handle to the memory 
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block. It is not an address, just a handle, Windows programs use the memory handles to keep track of memory blocks. 

- Before we can copy the string to the memory block, we need to lock the block in memory by using LocalLock(). This 

‘function returns the current address of the memory block we allocated. The block is fixed in memory at this point. 

Windows will not be able to move the block unless LocalUnlock() is called. When the memory block is locked, it is just 
like fixed memory allocated in an MS-DOS program. The strepy() function copies a string into the memory area. Once 

the string is loaded, there is no reason to leave the memory block locked. LocalUnlock() is used to free the block so 

that Windows can move it if necessary. If the block is moved, it will still contain the same character string, but at a 
new address. The handle hMem remains valid and still refers to the same memory block no matter where it is moved. 

The pStr pointer to the old address is invalid as soon as LocalUnlock() is called. 

Later in the program, we might want to output the text string using the TextOut() function. If this is the last time 
we will need the data, we can free the memory block, returning it to Windows to use for the next memory need. Here 
-is an example . 
pStr = Localtock ChMem) 3 
TextOut (hOC, 10, 10, pStr, strlen (pStr)) ; 

LocalUnlock (ChNem) ; 
LocalFree (hMem) ; 

Again, the block is locked only for the period of time when the string value in memory is et used. As Soon as 
that activity is over, LocalUnlock() is called to allow the block to be moved. In this case, the memory block was no 
longer needed. LocalFree(} was called to return the memory block to Windows, for use by any other application. 

_ If separate parts of an application can lock the same block of memory, the block can be locked more than once. 

_ Windows keeps track of the number of times a block is locked as the “lock count.” Calling LocalLock() increases the 

lock count by one. Calling LocalUnlock() reduces the lock count by one. An equal number of LocalLock() and 

LocalUntock() calls is needed before the memory block is free to be moved in memory. These examples have omitted 

the logic for dealing with situations where Windows did not have room to allocate the needed memory. See the ex- 
ample program under 7 LocalAlloc() function description for a more complete listing. 


_ Allocating Memory in the Global Heap 


As mentioned previously, the local heap is limited to the size of the 64K automatic data iene For large memory 
blocks, the global heap provides much larger areas from which to work. Global memory objects use the full 32-bit 
segmented memory addresses. 

The following example below again shows a 128-character buffer being allocated and used to store a string. In this 
case, the memory is allocated on the global heap. 


static HANDLE hMen ; 
LPSTR tpStr ; 


hMem = GlobalAlloc (GMEM_MOVEABLE, 128) ; 
tpStr = Globaltock ChMem) ; 

Lstrepy (lpsStr, "Hi ehere.”? m1 
GlobalUnlock ChMem) ; 

Note that the /pStr address pointer is now a long pointer to a string (LPSTR), a 32-bit value. A string copy function 
capable of handling the far pointers like Istrepy() is also required. Otherwise, the allocation of the global memory 
block exactly parallels the same activities for a block in the local heap. 

A side effect of segmented memory addressing for global memory is that the minimum size of a global memory 
block is 32 bytes. Windows will round up requests for “uneven” sizes of memory to the nearest 32 bytes. For example, 
a request for a global memory block of 33 bytes will result in 64 bytes being allocated. Using the global memory block 
is similar to local memory. We will assume that this is the last time the block is needed, so it is freed after use. If the 
block will be used again, the GlobalFree() function will not be called until after the last use. 

. UpStr = GlobalLock ChMem) ; 
TextOut (hOC, 10, 10, tpstr, tstrlen ClpStr)) ¢ 


GlobatUnlock (hMem) ; 
GlobalFree Chem) > 
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One thing to notice in these examples is that-the- 
handle to the memory object is of the same data type 
(HANDLE) for both giobal and local memory objects. 
Somewhere internal to the system, Windows maintains 
tables that keep track of where the actual meinory ob- 
jects are located. Some of them may be in the local 
heap, and some in the global heap. The only time the 
physical.address of the data is known to the program is 
when LocalLock() or GlobalLock() is called. The rest of SE io cele eae sancesanass ll 
the time you just trust Windows to keep track of the aici 1b. 5 After Block 21s Ta Block 9 Is Moveable. 
data. 


Moveable, Fixed, and Discardable Memory Blocks 


The majority of the time you will use moveable memory objects to store data in your programs. Windows provides two 
other types of memory for both the local and global heaps, (“fixed” and “discardable”). Fixed memory is just what it. 
sounds like, fixed in a certain location in memory. Fixed blocks are allocated with the LMEM FIXED flag when using 
LocalAlloc(), or the GMEM_FIXED flag when using GlobalAlloc(). 

Fixed memory should be thought of like taxes: sometimes necessary, but best avoided. To illustrate why, consider 

__ the case where three memory blocks have been allocated in a limited space. Memory Block 8 is fixed, as shown in. 

Figure 14-3. If block 2 is freed (deleted), the free memory is split into two parts, separated by Block 3. The fed block 
limits the maximum size of the next block allocated. (See Figure 14-4.) 

Now consider the case where all three of the blocks are allocated as moveable. In this case, Windows will be able 
to move Block 3 to make room the next time memory is requested. This makes a larger memory area available. (See 
Figure 14-5.) These savings multiply as the number of blocks increases. Conversely, one poorly written application 
that fixes a few blocks in the global memory area can reduce the performance of every other application running on 
the system. 

~~” ‘The opposite extreme from a fixed memory block is a discardable one. Discardable blocks are allocated with the 
moveable and discardable flags set, which allows Windows to move the block to make room. If the available room is 
still not big enough, discardable blocks are reduced in size to zero bytes to make more room. The most recently used 
discardable blocks are the last to be discarded. : 

To visualize how this works, consider a case, as illustrated in Figure 14. 6, where two discardable and one move- 
able block are allocated. If a large memory block i is requested, Blocks 1 and 2 can be discarded, and Block 3 moved. 

This makes the maximum amount of space available. 
This type of compression can be forced by calling the LocalCompact() and GlobalCompact() functfons. Moveable 
- memory blocks are moved before any blocks are discarded. The minimum number of blocks are discarded to make the 
required memory space available. 

‘Discardable memory blocks are typically used to store data that can be retrieved from disk. Program response i is 
much faster if the data stays in memory. If the system demands it, the data can be shed, and then reloaded when 
needed. Some typical examples include saving graphics images which are only displayed in certain parts of the appli- ~ 
cation, and database applications. The memory handle for the discarded block remains valid even after the block has 
been discarded. Memory blocks will not be discarded if they have been locked. Memory blocks can be resized at any 
time. The LocalReAlloc() and GlobaiReAlloc() functions do the work. The existing data is not destroyed if the block 
size is increased. You can check the size of a block at any time by calling LocalSize() or GlobalSize(). You can also — 
check the status of a block (locked, unlocked, discarded, discardable) using LocalFlags() or GlobalFlags(). 


Figure 14-6. Three Memory ‘Blocks Allocated, . . hae 14 7 Memory after a 1 Reaiiest for a Large 
Two Discardable. . Allocation. | | Acie pos 
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Traps to Avoid 


If your program has just finished processing a Windows message and control passes back to Windows via the program's 
message loop, Windows has control. If your program is actively. processing a message in the WndProc() function, or is 
in a program function called from within WndProc(), your application has control. Windows will not “jump in” and 
move memory around. Remember that Windows is a “nonpreemptive multitasking”: systent This means that your 
program has to give Windows control, Windows cannot take control by itself. : 

The impact of giving Windows control is that the stack will be changed, because an application only has one stack, 
and it is used by different functions. Listing 14-1-is a simple example showing correct and incorrect uses of automatic 
(stack) variables. 


> Listing 14-1. Automatic Variables 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD HF anan, LONG lParam) 
{ 


int i, n; /* automatic (stack) variables: */ 
static int m; /* static variable */ 


switch (iMessage) /* process windows messages */ 


case WM_CREATE: 
n= 20; /* mn initialize here to 20 */ 
for (i =O; i<n; i++) 
/* do something */ 
break ; 
case WM_| KEYDOWN: 
for (i =O; i<n; itt) /* WRONG!, nis */ : 
/* do something */ /* no longer 20 */ 
break ; 
/* rest of program here. */ 


This example shows a classic Windows programming error under the WM_KEYDOWN case. The automatic vari- 
able 7 cannot be assumed to be equal to 20, as Windows must have gained control between processing WM_CREATE — 
and processing WM_KEYDOWN. The correct practice here would be to use the static variable m in place of” in both — 
locations. Statics retain their value, even if Windows moves objects in memory. Note that the automatic variable 7 is 
used correctly in these examples, as it is initialized to zero within the for() loop for each message processed. 

The other situation to be careful of is storing far pointers to moveable memory instead of storing the handle to a 
memory block. When more memory is allocated, old memory blocks may be moved to make room. The handle to the 
memory block will remain valid, but not the old pointer to an absolute address. Avoid this problem by using the 
memory handle to keep track of memory blocks. Only determine the absolute address of the memory block for the 
short period of time that the block is locked for reading or writing. 


Windows Memory Configurations 

With Windows versions 3.0 and 3.1, there are three possible memory configurations: Real, Standard, and Enhanced. 
Real mode is like the old 2.0 version of Windows. Memory is limited to a 640K block. Standard mode allows access to 
up to 16 megabytes of memory. Enhanced mode allows access to 16 megabytes of memory and automatically swaps 
data off to the disk if memory runs short. Swapping data makes the “Virtual memory” limited only to the size of the 
hard disk. 

For 99% of all applications, you can forget about what kind of computer and/or memory model your and user has. 
Programs run faster on 386 and 486 machines with a lot of memory. Your program will run on more limited hardware 
if you follow basic Windows programing practices. 

e Keep memory blocks reasonably sized, ideally less than 32K each. 

e Use moveable and discardable memory blocks wherever possible. 

e _ Avoid fixed memory blocks if at all possible. ee be ey 
ae Keep code segments small, ideally less than 8K each. 


615° 


‘WINDOWS AP! BIBLE _ 


£ Youcan dey the type of memory model and memory hardware in use. _ GetWinFlags() will determine the CPU 
_ type, memory configuration, and Windows operating mode the eam is Use. 


- Moveable Program Code 
Data is not the only thing being moved around in memory. Windows is also busy moving pieces of your program around. 


Back in Chapter 1, we saw that a .DEF module definition file was needed e ome the GENERIC.C application. Here 
is what GENERIC.DEF looks like. 


NAME ‘GENERIC 

DESCRIPTION "generic windows program’ 
EXETYPE WINDOWS 
STUB "WINSTUB.EXE' : 

CODE os PRELOAD MOVEABLE 

DATA PRELOAD MOVEABLE MULTIPLE 
HEAPSIZE 1024 

STACKSIZE 5120 

EXPORTS WndProc 


. A couple of these terms may start to look familiar. The HEAPSIZE statement sets the minimum size of the 
program's local heap at 1,024 bytes. It will grow if the program uses LocalAlloc() and LocalReAlloc() to demand more 
than 1,024, STACKSIZE specifies the size of the stack. In this case, the minimum stack size of 5,120 bytes is specified. 

-Two other critical lines are the CODE and DATA statements. The CODE is specified as PRELOAD MOVEABLE, 
which means that all of the program is loaded into memory when the program begins. All of the parts of the program’ S 
code will be moveable in memory. Similarly, the DATA statement specifies PRELOAD MOVEABLE MULTIPLE. MUL- . 
TIPLE means that more than one instance of the program can be run, each instance with ifs own data. 

You can get more specific with a program’s segments, and set up separate attributes for different segments by 
using the SEGMENTS statement in the .DEF file. This statement is described later in this chapter in the section on 
module-definition statements. An example that uses different segment attributes is given under the GetCodeHandle() 


. function description. 
_ The choices for the program’s code segments are 
FIXED _ The program code is fixed in memory. This Satacien should only be used for critical appli- 


cations, such as interrupt processing functions, that must be located in fixed memory. Keep. 
these parts of the program as small as possible, and load them early. 


MOVEABLE -_ The normal case. The code segments can be moved in memory to make room. The movement 
has no effect on the way you program most applications. 


- DISCARDABLE Always combined with MOVEABLE. This configuration allows Windows to discard segments of 
. the program that have not recently been used if space is needed. The segments will be re- 
loaded if functions within the segment are called. Use this setting for as much of the program 
as possible, particularly portions containing seldom-used functions. In most cases, you will 
not make the central WndProc() function DISCARDABLE, as too much time will he taken 
‘loading it back from the disk. 


In addition, you can specify either PRELOAD or LOADONCALL. LOADONCALL works best for parts of the pro- 
gram that are not needed when the program first starts. 


Compiler Memory Models 
When you compile a Windows program using the Microsoft C compiler’s default small memory model, all of the code 
ends up in one segment. Windows had no choice but to treat the entire segment as a single block. The CODE state- 
ment in the .DEF file determines if the code segment is MOVEABLE, PRELOAD, etc. 

. When you.compile a Windows program using the: medium memory model, each source code file ends up compiled 
intoa separate segment. The startup code and any library functions that are used end up in a segment named _ TEXT. 
Other files‘are compiled into segments given the file name followed by _TEXT. For example, if two files GENERIC.C 
and HELPERS.C are compiled and linked to make one application, the application will end up with three segments: 
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_TEXT, GENERIC_TEXT, and HELPERS_TEXT. Windows keeps each of these parts of the program’s code separate, 
and it can move each segment independently if needed to make room. As you can see, the medium memory mocels is 
the model of choice for all but the smallest Windows programs. 

The other memory models, compact and large, are seldom used in Windows programs because they ais that 
all data segments be fixed in memory. There is no reason to use the compact or large model. Windows provides 
. excellent support for allocating blocks of memory in the global heap using GlobalAlloc() and the related functions. 


Locked, Fixed, and Page-Locked Memory Blocks 


In ‘most situations, you can consider a locked memory.block to be stationary in memory. Pointers to locked memory 
blocks remain valid between messages, memory allocation of other blocks, etc. Normally, this is all you have to worry 
about. In a few situations, such as when writing device drivers, you may need to know exactly where a memory block 
is located. You may be in for a shock, as it turns out that locked memory blocks can be moved, without invalidating 
pointers to the block. There are a couple of reasons for this. 


1, Inenhanced mode, memory blocks can be temporarily copied off onto the system’s hard disk. This technique.is 
called “virtual memory.” If data or code within the portions copied to the hard disk is needed, it is copied back 
into the physical memory. Pointers to the memory block remain valid, regardless of whether the data is in “real 

" memory” or on the disk. 


2. The built-in memory management logic in the 80386 and 80486 chips is sophisticated. In the protected-mode 
memory management scheme that Windows uses, the 80x86 chip maintains tables that translate a logical address 
called a “selector” into a physical address in memory using lookup tables. The tables (called the Local Descriptor 
Table and Global Descriptor Table) are maintained by Windows. Because of this translation, it is possible for a 
logical Windows address (pointer) to point to different physical locations in: memory if one of the descriptor 
tables is changed to make better use of available memory. 


As mentioned above, you will normally not have to worry about this low. level management of memory. In fact, the 
transparency of Windows’ handling of real and virtual memory is a major advantage to the developer. If you do need to 
control the physical memory location of one or more blocks, you can use the GlobalFix() or GlobalPageLock() func- 
tions. GlobalFix() assures that a memory block is not, moved in linear memory. The block can still be copied off onto . 
the hard disk. GlobalPageLock() really locks the block down. Not only is a page- -locked block stationary in physical 
memory, but it cannot be copied off to the hard disk. Norinally, GlobalPageLock() is used with GlobalDosAlloc() to 
_ page-lock a memory block that can be accessed by both Windows and DOS applications. This is useful if a DOS device 

driver or interrupt handler is being used under Windows. Fixed and page-locked memory blocks will limit Windows’ — 
ability to cptimize memory use. Only use these features when necessary. 


Running Other Modules 


In Windows, the term “module” is used to describe a running program, including all its glaciated data and code 
segments. Windows has a number of functions for working with modules. The most frequently used is LoadModule() 
which loads and runs another program. A similar function, WinExec(), also loads and runs programs, 

Some modules, such as the graphics and sound modules that Windows loads, are used by many applications, Each 
application that calls the module increases the module's “reference count” by one. In order to remove a module from 
- Memory, the FreeModule() function must be called as many times as the current reference count. The reference 
count can be determined with GetModuleUsage(). You may also find it useful to determine the name and path name 
of the file that was loaded to create the module. GetModuleFileName() does this. Direct support of loading and 
running other programs from within your Windows program opens up a lot of possibilities. If you do not like the 
standard program manager, write your own version! . . 


Module-Definition Statements 


‘There are twelve statements that can be used in an application’s .DEF module definition file. The LINK.EXE linker 
. application uses the .DEF statements to control the final linking of the application’s code, data, and resources, .DEF 
files are standard ASCII text files. The statement names must be capitalized, as shown in the following example. 
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C> GENERIC.DEF Definition File 


NAME 
DESCRIPTION 

EXETYPE WINDOWS 

STUB 

CODE 

DATA 

SEGMENTS 


HEAPSIZE 
STACKSIZE 
EXPORTS 


GENERIC 
"generic windows program! 


"WINSTUB.EXE'. 
PRELOAD MOVEABLE 


RELOAD MOVEABLE MULTIPLE 


MAINSEG MOVEABLE 

SECOND: LOADONCALL FIXED DISCARDABLE 
1024 F 

5120 : 

WndProc . 
nStrCopy 


In the statement Geserintions option choices are surrounded by square brackets. The possible choices are sepa- 
rated by a vertical line ((). vat 


Module-Definiton Statement Desciptions 


CODE mWin2.0- mWin3.0  mWin3.1 
Purpose Defines the attributes of the application's code segment. 
Syntax CODE [FIXED | MOVEABLE] [DISCARDABLE] Eee | LOADONCALL] 
Example _ CODE PRELOAD MOVEABLE 
Description This statement is required. The FIXED option makes the application’s code fixed in memory. . 
= 8 MOVEABLE is preferred, as it allows Windows to move code segments to make better use of 
memory. DISCARDABLE i is ideal for seldom-used portions of the program, as the discarded por- 
tions will be reloaded if a function within the segment is called. Dynamic Link Libraries must use 
the DISCARDABLE option if the code is to be MOVEABLE. 
Specifying PRELOAD causes all of the program’s code to be loaded at startup. LOADONCALL 
allows windows to wait until a portion of the application is needed before loading it into memory. 
| If there are conflicting options on the CODE line, MOVEABLE overrides FIXED, and PRELOAD 
overrides LOADONCALL. ° . 
, Individual portions of the application’s ‘code can be given different attributes by using the 
: eee statement. See its description below. 
DATA ee mWin20 mWin30 mWin3l 
Purpose Defines the attributes of the application’s data segment. ‘. 
Syntax DATA [NONE | SINGLE | MULTIPLE}-[FIXED | MOVEABLE} 
Example DATA PRELOAD MOVEABLE MULTIPLE 
Description The NONE option causes the application to be linked without a data en This must be the 
only option on the line. This is only applicable to Dynamic Link Libraries (DLL). The SINGLE 
option also applies to DLLs only. This means that there is only one data segment for the applica- 
tion. MULTIPLE is the standard option for .EXE programs, as each instance of the application 
has a separate data segment. The FIXED option causes the data segment to stay at a fixed memory 
location. MOVEABLE is preferable, as it allows Windows to make maximum use of available 
memory. . 
DESCRIPTION | | a 8 mWin2.0 mWin3.0  mWin31 
Purpose ‘Embeds a text string in the beginning of the application scode. 
Syntax . DESCRIPTION ‘text’ 
Example DESCRIPTION ‘Property of XYZ Co. All Rights Reserved’. 
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| Description 


EXETYPE 
- Purpose _ 
Syntax 
Example 
Description 


_This-is usefulfor putting copyright notices into code. The text ends up about 735 bytes from the 
__ beginning of the file, as the Windows stub ends up in front of the beginning of the application’s 


= e0de (see STUB below). 
OWin20 m@Win30 mWin3! 
Tells the linker if the application is a Windows or an OS/2 probe 
___EXETYPE [WINDOWS | 08/2] 
EXETYPE WINDOWS 
This is a requirement with the 3. x versions of Windows. 
mWin2.0 gWin30 wmWin3d) 


EXPORTS 


~ Purpose 
Syntax 
exporiname - 


ordinal 


Defines the names of functions that will be exported to other applications or passed to Windows 
functions. Also defines the callback functions used by such functions as EnumWindows(). 


EXPORTS exportname (@ordinal] [RESIDENTNAME] [NODATA] [parameter] 

The function name of the functions to be exported. You can give the functions an alias to be used 
by other applications by following the exportname with an equal sign and a second name. For 
example, ; 

ChangeFileName=FileName 

allows other applications to use the function name FileName(), even though the source code 
defines the function as ChangeFileName(). 


Defines an optional ordinal number value. The number must be preceded by an @ character. 
Ordinal numbers are used by Dynamic Link Libraries as a shortcut way to refer to the functions 
inside of the DLL. For example, 


EXPORTS FileNameFunc @1 


—“gets the FileéNameFunc() function as the number 1| function ‘in the library. See Chapter 28, Dy- 


namic Link Libraries, for a complete example. 


RESIDENTNAME = Specifies that the function’s name must be resident at all times (not just the ordinal value). 


NODATA .- 
? Parameter 


Example 


Description 


HEAPSIZE 


Purpose 
Syntax 


An option that specifies that the function is not bound to a specific data segment. The function 
~ uses the current data segment when the function is called. 


An optional integer that specifies the number of words the function expects to be passed as pa- 
rameters. Checking that the number of parameters inately is a crude form of type checking. 


EXPORTS 
FunctionFirst @1 
FunctionSecond @2 
FunctionThird=AliasThird @3 
See the examples under the GetCodeHandle() function description for more corapiele ex- 
amples including DLLs. 


Specifying the function name in the EXPORTS section of the program's .DEF definition file is an 
easy thing to forget, and doing so causes unpredictable program crashes. Dialog box functions 
and callback functions must be exported. DLL functions must be exported if ey are to be called 
from other applications. . 

mWin 2.0 . 


Win3.0 mWin3.1 


Specifies the size of an application’s local memory heap. 
HEAPSIZE bytes 
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modulename 


An integer between 0 and 65,536. The minimum size above zero is 256 bytes. 
HEAPSIZE 1024 


The default heapsize is zero, so HEAPSIZE must be specified for applications. Some DLLs may 
not need a heap. The heap wil! be automatically expanded if the application calls LocalAlloc( or 
LocalReAllocQ), requesting space larger than the current heap. The heap will ee until 
LocalShrink() i is called. 


& Win 2.0 eWin30 @ Win 3.1 
Specifies the names of the functions that will be imported from Dynamic Link Libraries (DLLs). 
IMPORTS [infernal- name} modulename [entry] 


An optional alias that the application will use for the function. The alias must be followed by an | 
" equal sign and the function’s name as defined in the DLL. For example, : 


IMPORTS Reader=Samlib.FileRead 


specifies that the function name Reader() will be used = the application for a function { in 
SAMLIB.DLL called FileRead(). 

The name of the DLL module. This will be the same as the file name of the .DLL file. For cxanpl, 
SAMLIB.DLL will create a module SAMLIB when loaded into memory. 

The function to be imported. This can either be the function's name, or the function's ordinal 
number as specified in the DLL's definition file in the EXPORTS section (see EXPORTS above). _ 
The function name or ordinal number must be preceded by a period to separate it from the mod-~ 
ule name. . 


IMPORTS FileLib.ReadFile 


FileLib.1 
MyName=FileLib.FuncName 


IMPORTS is an optional statement. It is used only if the application uses functions that are de- 
fined in a Dynamic Link Library. See Chapter 28, Dynamic Link Libraries, for a full description. 


eWin20 @Win30 @Win3l 
Names a Dynamic Link Library (DLL). . 
LIBRARY libraryname 


~ LIBRARY MyDLL 


This statement is similar to the NAME statement, a that LIBRARY is used for DLLs. If 
libraryname is left blank, LINK will use the library file name without the extension. 


@Win20 wWin3d0 Wind! 
Defines the name of an application's module. : 
NAME modulename 

NAME generic 


The modulename must match the executable file name. For eaiaais GENERIC.EXE must have 
a module name GENERIC. If modulename is left blank, LINK will use the file name without the 


- extension. If both NAME and LIBRARY are missing from the .DEF file, LINK will assume that 
NAME was implied and use the file name to create an executable file. 
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SEGMENTS , BWin2.0 mWin3.0 mWin3.1 
Purpose Specifies the attributes of code and data segments. | 
Syntax SEGMENTS segmentname [CLASS ‘class-name’] [minalloc] [FIXED | MOVEABLE] 


[DISCARDABLE] [PRELOAD | LOADONCALL] 


segmentname The name of the segment. If default names are used, TEXT will be the code segment name, and 
_DATA will be the data peanut name. Use the Microsoft C compiler -NT switch to name code 


. segments. 
_class-name_ An optional character string, aartounieat in single quotes, specifies the class name. If no class 
name is specified, LINK uses the name ‘CODE’ by default. 
minalloc _  Anoptional integer that specifies the minimum size to allocate for the segment. 


FIXED specifies that the segment must remain at one location in memory. MOVEABLE is 
preferred, as it allows Windows to make maximum use of available memory. . 

DISCARDABLE specifies that the segment can be discarded if memory space is needed for 
another use. 

The PRELOAD option causes the segment to be loaded when the application is started. 
LOADONCALL allows the segment to be left on disk until a function within the segment is called. 


Example See the example under the GetCodeHandle() function description. 


Descriptica The SEGMENTS statement allows individual control over how each segment of the program is set 
up during linking. Common uses are to set the less frequently used code segments to 
DISCARDABLE and LOADONCALL. This speeds program startup, and minimizes memory con-. 
sumption by the remote parts of the program. 


STACKSIZE ; : SWin20 mWin 3.0 wWin3.1 


Purpose: Specifies the size of the program’s stack. 

Syntax | STACKSIZE bytes 

bytes An integer value. The minimum size is 5,120. 

Example STACKSIZE 6144 i 
Description The local stack is where automatic variables are stored. Because Windows programs are reen- 


trant (different parts of the same program may be executed in parallel), a large stack is needed. 
Dynamic Link Libraries use the calling application’ s stack. Do not use the STACKSIZE statement 


with DLLs. 
STUB eWin2.0 mWin30 mWin31 
Purpose . Specifies which “stub” file to anend to the front of the re 
Syntax STUB filename’ 
Example “STUB ‘WINSTUB.EXE’ ; 
Description Ifyou try to run a Windows program ‘ious MS-DOS, the program will- terminate with a warning — 


message that the application needs Windows to run. This action takes place because Windows | 
applications have a small “stub” file placed on their front. The stub file shows the message onthe 
screen, and then terminates the program. The stub file is nothing more than a small MS-DOS 
application. You can substitute your own stub file if desired. 
\ 
Memory Function Summary — 
Table 14-1 summarizes Windows memory manangement functions. The detailed faitstion escintions are in the next Zi 
ceca 
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FreeModule- 
GetCodeHandle 
GetCodelnfo — 
GetCurrentPDB 
GlobalDosAlloc 
GlobalDosFree 
GlobalFix 
GetFreeSpace 
GetModuleFileName 
GetModuleHandle 
GetModuleUsage . 
GlobalAlloc 
GlobalCompact 


GlobalDiscard 
GlobalFlags 
GlobalFree 
GlobalHandle 
GlobalLock. 
Global RUNewest 
_GlobalL RUOldest 
GlobalNotify 
GlobalPageLock 


GlobalPageUnlock 
GlobalReAlloc 
GlobalSize 
GlobalUnfix 
GlobalUnlock . 
GlobalUnWire 
GlobalWire 
LimitEmsPages 
LoadModule — 


LocalAlloc 
LocalCompact 


LocalDiscard 
LocaiFlags 


Removes a module from memory. 


Determines the code segment of a function, and/or loads a code segment into memory. 
Determines information about a code segment. 

Returns the segment address of the DOS PDB (PSP). 

Allocates a memory block that can be accessed by both DOS and Windows. 


Releases a block of memory allocated with GlobalDosAlloc{ ). 


Stops a memory block from being moved in memory. 

Determines the amount of memory left in the global heap. . 

Determines the full file and pathname for the executable file from which a module was loaded. 
Retrieves the handle of a module given the module’s name. 

_ Retums the reference count of the given module. 

Allocates a block of memory in the global heap. 


Compacts memory in the global heap, and determines the size of the largest available memory 
area. ~ 


Discards a memory block from the global heap. 

Determines if a memory block in the global heap is locked, discarded, or potently discardable. 
' Frees a block of memory allocated in the global heap. bee bee Steet 

Retums the handle of a global memory block, given its address. 

Locks an allocated memory block in the global heap. . 

Marks a memory block to be the last one to be discarded in the global heap. 


. Marks a memory block to be the first one to be discarded in the global heap. 


Installs a notification function, which is called if global memory objects are about to be discarded. 


Stops a memory block from being moved in linear memory, or from being written to disk me 
memory inhibited). 


Unlocks a memory block locked with GlobalPageLock( ). 
Changes the size and/or attributes of a global memory block. 
Determines the size of a memory block allocated in the global heap. 


Frees a memory block fixed by GlobalFix(). 


Unlocks a locked memory block in the global heap. 

Unwires a wired (locked) block in the global heap. 

Locks a global memory block in low memory. Fe 

Limits the amount of expanded memory that Windows will assign to an application. 


Loads and executes a Windows program, or creates a new instance of the program if one or more 
instances are already running. : 7 


Allocates a block of memory in the local heap. 


Determines the amount of available memory in the local. heap, compacting memory if necessary ie a 
increase space. : 


Discards a memory block from the local heap. 


- Determines if a memory block in the local heap is locked, discarded; or potentially discardable. 
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LocalFree 


LocalHandle . 


LocalLock 
LocalReAlloc 
LocalShrink 
LocalSize 
LocalUnlock 


LockSegment 


Mu!Div 


UnlockSegment 


WinExec 
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Frees a block of memory allocated in the local heap. 

Retrieves the handle of a memory block, given the address. 

Locks an allocated memory block in the local heap. 

Changes the size and/or attributes of a local memory block. 
Reduces the size of the local heap. 

Determines the size of a memory block allocated in the local heap. 
Unlocks a locked memory block in the local heap. 

Locks a segment in memory. 

Computes the result of (a * b) /c, where a, b, and c are short integers. 
Unlocks a memory segment locked with LockSegment(). 

Loads and executes a Windows program. 


Table 14-1. Memory Function Summary. 


Memory Function Descriptions en 
This section contains detailed descriptions of the memory management functions. 


FREEMODULE 


Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
hModule 


—_— Example 


\ 


Ss 


- module in the global memory area 
- every time a WM_PAINT message is 
‘- received. The full file name of the 


Win2.0 @Win3d.0 mWin3l 


Removes a module from memory. 
void FreeModule(HANDLE hModule);. 


A module is a running application. Every time a module is loaded by another program, the 
module’s usage count is increased by one. FreeModule() reduces the usage count by one. It re- 
moves the module from memory if the module’s usage count is reduced to zero. 


Used to remove modules that do not have visible windows from memory. To remove a module that © 
has a visible window, send the window a WM_DESTROY message with SendMessage(). To remove 
a DLL (Dynamic Link Library), use FreeLibrary(). 


No returned value (void). 
FreeLibrary(), LoadModule(), GetModuleHandle(), GetModuleUsage() 


HANDLE: The handle of the module to free. This value can be obtained by calling Get- 
ModuleHandle(). 


This example, as illustrated in Fig- 
ure 14-8, checks for the “SOUND” 


Figure 14-8. FreeModule() Example. 


file from which the sound driver was 
loaded is displayed, as well as the 
number of times the driver has been called by running applications. The usage count will equal 
the number of running applications on the system, as Windows loads the SOUND driver for all — 
applications. If the user clicks the “Do It!” menu item, the sound driver is freed. FreeModule() is ' 
called once for every usage count. The HEAPWALK application that-comes with the Microsoft 
“<Windows SDK can be used to vy that the SOUND module has been removed from. BEM: 


0 


eet : ; x z 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


PAINTSTRUCT ps; 
static — HANDLE hModule ; 
char cBuf [256], cWindName [643 ; 
int nCount, i ; 
switch (iMessage) . /* process windows messages */ 


case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
hModule = GetModuleHandle (“sound”) ; 
nCount = GetModuleUsage (hModule) ; 
GetModuleFileName (hModule, cWindName, 64) ; 
TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
"  “""Fdle %s, Useage = %d"", (LPSTR) cWindName, nCount)). ; 
EndPaint ChWnd, &ps) ; 


break ; 
case WM_. COMMAND: /* process menu items */ 
; switch (wParam) 
hina . C - 
case IDM_DOIT: /* User hit the "Do it™ menu item */ 
nCount = GetModuleUsage ChModule) ; 
for (i = 0; i < nCount ; i++) 
FreeModule ChModule) ; 
break ; 
case IDM_QUIT: pare /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; eo ae: Os 
} 
- break ; ae kK gtts ed . 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; : 
default: | , /* default windows message processing */ 


return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; 


> 

GerCopEHANDLE 4 eWin2.0 mWin30 mWin3.l 
Parpose Determines the code segment of a function, and/or loads a code segment into memory. 

Syntax . HANDLE GetCodeHandle(FARPROC lpProc); . 


Description N ormally, applications let Windows load code segments either on‘startup (PRELOAD attribute in 
the .DEF file), or when first needed (LOADONCALL attribute)..GetCodeHandle() allows an ap 
plication to control when a segment containing a function is loaded. . 

_ Uses Can be used to load a series of segments in advance, during an _oeeearees 
a '  jdle period: Doing so avoids the delay of waiting for LOAD- a generic [~[- 


ONCALL segments to be loaded. TP pott! Quit 


Returns HANDLE, the code segment containing the function. . f= 

See Also . Rettonelnid); cen oeuetanlie@ _ | Block moveable , 

Parameters: - f. Segment = 0x4 

lpProc phrmoo.'t The sroceduntistaiies address of the fiction to | Size = 86 (0= 64K) 
. load. Retrieve this value with MakeProcInstanceQ). ot Moveable. 

Example This example, which is illustrated in Figure 14-9, demonstrates 


named code segments, using GetCodeHandle() to load acode Figure 14-9. GetCode- ~ 
segment into memory and using GetCodeInfo() to determine Handle() and rai D- 
information about the code segment. eae! 
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The application’s make file specifies the medium memory model and debugging options, and 
it also uses the Microsoft C eomailen ity switch to name two code segments as “MAINSEG” and 
“SECOND.” 


© GENERIC.NMAKE File 


ALL: generic.exe 


CFLAGS=-c ~D LINT_ARGS -AM -Zi -Od -Gsw -W2 
LFLAGS=/NOD /co 


generic.obj : generic.c generic.h 
$(CC) SCCFLAGS) -NT MAINSEG generic.c 


second.obj : second.c 
$(CC) SCCFLAGS) -NT SECOND second.c 


generic.res: generic.rc generic.ico 
re -r generic.rc 


generic.exe : generic.obj second.obj generic.def generic.res 
Link SCLFLAGS) generict+second, , ,libw mlibcew, generic 
rc generic.res 
The definition file specifies separate memory attributes for the two named segments. The 
segment named SECOND is fixed not loaded until needed, and set as DISCARDABLE, as the 
nStrCopy() function in this segment will only be used once. 


© GENERIC. DEF Definition File 


NAME GENERIC 
DESCRIPTION ‘generic windows program' 
EXETYPE WINDOWS 
sTuB "WINSTUB.EXE' 
CODE PRELOAD MOVEABLE 
DATA PRELOAD MOVEABLE MULTIPLE 
SEGMENTS MAINSEG MOVEABLE 
t SECOND LOADONCALL FIXED DISCARDABLE 
HEAPSIZE 1024 
STACKSIZE 5120 
EXPORTS WndProc 
nStrCopy 


A small function will be in the fixed memory segment. In this case, the function is just a 
string copy function. This example is purely for demonstration. This simple function does not 
need to be in a fixed data segment. 


© SECOND.C Listing 


‘/* second.c a second c program file with a separate segment */ 
#include <windows.h> 


int FAR PASCAL nStrCopy (char *pDest, char *pSource, int nMax) 
: inti; 
for Ci = 0; i < nMax ; i ++) ; 
: if ¢! MIBDES EES = *pSource++)) , 


break ; 
Xv 


Py 


return Ci) ; 
When WM_CREATE is received, the application loads the code for the nStrCopy() function 


by calling GetCodeHandle(). The returned segment value hCode is not used in this camps The 
loaded function is used to copy a string to a local memory block. iy 

Ay} 

ie 
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When the “Do It!” menu item is clicked, the application uses GetCodeInfo() to retrieve infor- 
mation about the code segment containing the nStrCopy() function. Some of this information is 
‘displayed on the application’s client area, as shown in Figure 14-9. 


> GENERIC.C Listing 
long FAR PASCAL WndProc CHWND hind, unsigned iMessage, WORD wParam, LONG Param) _ 
{ 


PAINTSTRUCT ps + 
static HANDLE hem ; 
—~char-~ *oMen ; 
“char. . cBuf £128] ; 
FARPROC ' fpProc ; 
_HANDLE ae hCode ; 
WORD 0... wValue £8] ; 
.-- HDC o . hDC ; 
"> switch CiMessage) - /* process windows messages */ 
q 


case WM_CREATE: 
fpProc = MakeProcInstance (nStrCopy, ghInstance) ; 
hCode = GetCodeHandle (fpProc) ; 
hem = LocatAtloc (LMEM_MOVEABLE, 128) ; 
pflem = LocalLlock (hMem) ; 
betes nStrCopy (pMem, "Block moveable", 14) ; 
LocalUnlock (hem) ; 
FreeProciInstance (fpProc) ; 
- break ; : 
case WM_PAINT: 
BeginPaint ChWnd, &ps) ; /* note no locking of hMem */ 
pMem = LocalLock ChMem) ; 
TextOut (ps.hdc, 10, 10, pMem, strlen (pMem)) ; 
LocalUnlock (hMem) ; 
EndPaint (hWnd, &ps) ; 
break ; ; 
ease WM_COMMAND: ' /* process menu items */ 
switch (wParam) ; 
{ 


_ case IDM_! DOIT: /* User hit the. “Do it" menu item */ 
GetCodelInfo (nStrCopy, (LPVOID) wValue) .; 
hOC = GetDC ChWnd) ; 
: TextGut (hdc, 16, 30, cBuf, wsprintf (cBuf, 
2 “Segment. = Oxzx", wValue £01)) ; 
F TextOut (hOC, 10, 50, cBuf, wsprintf (cBuf, 
"Size = %1 (0 = 64K)", wvalue C1])) ¢ 
if CuValue C2) & 0x10) 
TextOut (hoc, 10,.70, “Moveable”, 8) : 
else 
TextOut (hdc, 10, 70, "Fixed", 5); 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: -. me send end of application message af 
LocalFree (hMem) ; 
DestroyWindow (hWnd) ; : 


break ; 
} 
break ; ; 
case WA_DESTROYs - /* stop application */ 
PostQuitMessage (0) ; 
break ; ; 
default: /* default windows message processing */ 


return DefWindowProc Chiind, iheanage, wParam, lParam) ; 
}- : ; 
_ peturn COL) ; 
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GetCopEInro me | ee Win 2.0 mWin3.0  mWin3l ” 


Purpose Determines information about a code segment. 
Syntax < void GetCodeInfo(FARPROC /pProc, LPVOID lpSeglnfo); 
- Description This function copies information about a code segment into an array pointed to by IpSegInjo. 
Uses Determining the status of a code segment, such as if it is fixed in memory or moveable. 
Returns No returned value (void). : | 
See Also GetCodeHandle(), GetModuleHandle() 23 
Parameters we ae is 
lpProc _ FARPROC: The address of the function in the segment. This is the function name, not the proce- _ 


dure-instance address, The value is passed as segment:offset. The parameter can also be passed. 
as module handle:segment. Use GetModuleHandle() to retrieve the module handle. 


lpSegInfo LPVOID: A pointer to a 16-byte wide array. Information about the code segment is copied to this 
array when the function is called. The information is coded as shown in Table 14-2. 


0 The éffasty within the sector of the Sead faciok or data, eine to the Seanad of the sector..: 
re The size of the segment in the sector in bytes. Zero=64K. 
4 Contains flags which specify the attributes of the segment. These are set as follows: 


0-2 - Bit Ois 1 ifthe sential is a data (ee ees itisa ok segment 


3 Set to 1 if the segment is iterated, such as multiple data segments. 
4 Set to 1 if the segment is moveable; otherwise, the segment is fixed. 
5-6 Not used. 
7 If the segment is a code segment and bit 7 is 1, the segment is an execute- only segment. If 
___ the segment is a code segment and bit 7 is 1, the segment is a read-only segment.- 
e 8 If bit 8 is 1, the segment has relocation information. 
9 If bit 9 is 1, the segment contains debugging information. 
. 10-15 Not used. 
6. The amount of memory allocated for the segment. Zero = 64K. 


Table 14-2. GetCodelnfo() Data Array. 
Example. See the previous example under GetCodeHandle(). 


GeTCuRRENTPDB | mWin20 mWin30 mWin3.1 
Purpose Returns the segment address of the DOS PDB (PSP). 
Syntax — WORD GetCurrentPDB(void); 


Description Windows is a descendant of the MS-DOS operating system, which is a descendant of the CP/M 
operating system. Because of the desire to retain CP/M compatibility in the early days of MS-DOS, 
MS-DOS retained the Program Segment Prefix (PSP) data structure used by CP/M and added to 
it. The PSP is now referred to as the Program Data Base (PDB). 


\ 


WINDOWS API BIBLE 


pe Suenerien 9 Bee se [SPE 
: Dott! Quit — 


Do ith "Quit 


cd 20 3d 1a0 Yaf0 fe 1d f0 1c 0 2 10 9c4 


Figure 14-10. GetCurrentPDB() Example. | Figure 14-11. GetFreeSpace() Example. 


The current free space = 13059872 bytes 


The PDB contains basic information about an application, such as the address to call for MS- 
DOS file handling, and the address to call for a critical error. These fields are seldom needed from 
within a Windows program. For more information on i this data, refer to the MS-DOS Encyclope- 
dia (1988, Microsoft Press). ; 


Uses Rarely used. 

Returns WORD, the paragraph address (selector) for the current PDB. 

See Also _ GetCodeInfo(), GetCurrentTaskQ) 

Parameters ~ None (void). 

ayant This example, illustrated in igiee 14-10, prints the first 16 bytes of the program segment prefix 


(PSP) when the user clicks the “Do It!” menu item. 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD dire: LONG \Param) 
t 


WORD ~ WwPSP ;- 
“LPSTR ‘LpStr ; 
char cBuf £16] ; 
int : slo 
BYTE FAR *pcVal ; 
HDC hDC ; 
switch CiMessage) /* process windows messages */ 
{ 7 
case WM_COMMAND: /* process menu items ne 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it menu item at 
wPSP = GetCurrentPDB () ; . 
UpStr = (LPSTR) MAKELONG. CO, wPSP) ; 
hDC = GetDC ChWnd) ; 
for (§=0; 1< 16 : i++) 
{ es : : : 
‘peVal = (BYTE FAR *) (lpStr + i) ; 
Textout €hoc, i * 25, 10, cBuf, catanes (cBuf, 
"Ax", Cintd *peVal)) ; 


} 7 
ReleaseDC Chund, ‘hDC) ; 


. : break ; 
~ [Other program lines] . | 
GETFREESPACE oN mWin2.0 m@Wind0 em Windl 
Purpose “Determines the amount of memory left in the global heap. ; . 
Syntax § . DWORD GetFreeSpace(WORD wFlags); | 
Description. _—_—_—‘ This function adds all ‘of the unused memory in the global heap. The value reported may not be 


~ the size of the largest contiguous block of memory, as fixed memory blocks will break the memory 
Os area into smaller pieces. Use GlobalCompact() to find the size of the largest available contguens 
_ piece of memory in the global = 
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Uses Determining how much memory is left. If the value i is getting low, the application may want to 
shed unneeded data or resources. ; 
Returns DWORD, the number of free bytes. 
See Also GlobalCompact() 
Parameters a . : 
wFlags WORD: Normally set to zero. For systems running with extended (banked) memory systems, the 
value can be set to GMEM_NOT_BANKED to specify that only the amount of memory below the 
EMS bank line is returned. ; 


Related Messages WM_COMPACTING 


Example This example, which is shown in Figure 14-11, displays the number of free bytes of memory when 
the user clicks the “Do It!” menu item. 


\ 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) ' 
{ ‘ ; ; 
WORD - wPSP ; 


char cBuf (1281 ; 
DWORD dwFree; 
HDC hDC ; 


switch (iMessage) 


/* process windows messages */ 


case WM_COMMAND: /*® process menu items */ 
switch (wParam) . 
{ 
case IDM_DOIT: /* User hit the "Do it” menu item */ 

dwFree = Getrreespace (0) 

hDC = GetDC ChWnd) ; 

TextOut (hDC, 10, 10, cBuf, wsprintf CeBut, 

* CLPSTR) “the current use space = 211 bytes", 


dwFree)) ; 
ReleaseDC (hWnd, koe) ; 
break ; 

[Other program lines] 

GeTMopuLeFILENAME mWin2.0 mWin3.0 gWindl 

Purpose Determines the full file name and ‘path name for the executable file from which a module was 
loaded. 

Syntax int GetModuleFileName(HANDLE hModule, LPSTR lpFilename, int nSize); 

Description Amodule is a running application. This function determines the name of the file that was loaded 
to start the application. The file name will be preceded by the path name, such as “C:\WIN- 
DOWS\PBRUSH.EXE.” 

Uses The returned string can be parsed to find out which application a module handle represents. 

Returns int, the number of characters copied to [pFilename. 

See Also GetModuleHandle() 

Parameters 

hModule HANDLE: The handle of the module. This is the value returned by LoadModule(). 

lpFilename LPSTR: A pointer to a character buffer that will contain the file and path name. The buffer must 

be at least nSize characters wide. 

nSize int: The maximum number of characters to copy. 

Example 


See the example under LoadModule(). - 
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with other options. 
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“WINDOWS APIBIBLE are — 
GetMopueHanpuz ae: Win 2.0 Win3.0 Win 3.1 
Purpose Retrieves the handle of a module, given the module's name. | 
Syntax HANDLE GetModuleHandle(LPSTR lpModuleName); 

Description .. A module is a running application. This function returns the handle of a module. 
Uses The handle is needed to call FreeModule(). . 
Returns HANDLE, the module's handle. NULL on error. 

‘See Also - LoadModule(), GetModuleUsage(, GetModuleFileName() 

- Parameters _ 
lpModuleName __ LPSTR: Anull- terminated diarastee string containing the name of the module. This i is the same 
Qh as the program name, but without the extension. 

Example See the example under LoadModule(). . 

GeTMopuLeUSAGE 7 he wWin2.0 -aWin30 mWindtl © 
Purpose - Returns the reference count of the given module. ; 

Syntax int GetModuleUsage(HANDLE hModule); 

Description A module is a running application. 

Returns int, the reference count. This is the number of other applications that have caused the module to 

; be loaded. Modules are loaded by either calling functions in the module, or by explicitly loading 

. the module with LoadModule(). 
See Also GetModuleHandle(), LoadModule() 
Parameters 
hModule - _HANDLE: The handle of the module. 
Example See the een under or LeaModule(. 
GLoBALALLOC Win2.0 wWin30 mWin3l 
Purpose | _ Allocates a block of memory in the global heap. 
Syntax HANDLE GlobalAlloc(WORD wFlags, DWORD dwBytes); 
Description This is the first step in allocating and using memory in the global heap. The global heap size is - 
= limited only by the size of the system’s memory, less the room taken up by DOS, Windows, and the 
‘currently running applications. Global memory is allocated in blocks of 32 bytes. If the amount 
a requested is not a multiple of 32, the block size will be rounded upward to the nearest 32 bytes. 
Uses Global memory is ideal for large memory blocks. Access is slightly slower than with memory on 
the local heap, as the full 32-bit address is used to specify the memory location. 
Returns . HANDLE, the handle to the memory block allocated. Returns NULL on error. 
See Also GlobalLock(), GlobalReAlloc(), GlebalFreeQ), GlobalCompact() | . 
Parameters ers ed 
wFlags” WORD: One or more of the flags, listed in Table 14-8, combined with the C language binary OR 


operator (i). Choose either GMEM_ FIXED or pearl _MOVEABLE, and then combine the choice ‘ 


\ 


x 
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GMEM - DDESHARE MeeKait memory that can be shared by ge Seen data using ae data 
“exchange (DDE). See Chapter 30 for an explanation of DDE. This type of memory is 
automatically discarded when the application that allocated the block terminates. 


GMEM_DISCARDABLE Allocates memory that can be discarded if Windows needs to make room. Used only with 


GMEM_MOVEABLE. 
GMEM_FIXED Allocates fixed memory. Do not use this flag unless necessary. Fixed memory limits Windows’ 
: ability to optimize memory use. 
GMEM_MOVEABLE Allocates moveablememory. 7 
GMEM_NOCOMPACT Memory i in the global heap is not compacted or discarded to make room for the new memory 
block. 
GMEM_NODISCARD Memory in the global heap is not discarded to make room for the new memory block. - 
GMEM_NOT_BANKED Allocates memory that cannot be banked (EMS systems only). 
GMEM_NOTIFY , The notification routine, set by GlobalNotify(), is called if the memory object is to be discarded. 
GMEM_ZEROINIT Initializes the new allocated memory block contents to zero. 


Table 14-3. GlobalAlloc() Flags.. 


Whenever possible, use GMEM_MOVEABLE, WINDOWS.H includes two common combinations: 


#define GHND (GMEM_MOVEABLE | GMEM_ZEROINIT) | 


#detine GPTR (GMEM_FIXED | GMEM_ZEROINIT) 
dwBytes DWORD: The number of bytes to allocate. The actual number of bytes allocated may be a larger 


number in order to end the boundary on an address which is a multiple of 32. 
If GlobalCompact() was used to determine the maximum dwBytes value, GMEM_NO- 
COMPACT and GMEM_NODISCARD should not be used. 


Caution If the program's data segment is defined as moveable in the .DEF file, calling GlobalAlloc() may 
cause the data segment to move, which will invalidate stored far pointers. 
Example This example shows the allocation of memory in the global heap used to store a string. When the 


program first starts (WM_CREATE 
_ received), room for 27 characters is 
allocated. GlobalAlloc() actually al- 
locates 32. A string is stored in the 
memory block. This string, along 


; : The memory biock is 64 bytes in size. : 
with the block size and several Contains: ABCDEFGHUKLMNOPQRSTUVWXYZabcdetghykimnoparstuvwxyz 


Flags: Discardable: 0, Lock Count: 0 


memory status bytes, is displayed on 
the window’s client area every time Figure 14-12. GlobalAlloc() Example. — 

a WM_PAINT message is received. 

When the user clicks the “Do It!” menu item, the memory block is reallocated to make room for 
another 27 characters. The additional characters are written to the buffer and are displayed 
when WM_PAINT messages are processed. Repeatedly clicking the “Do It!” menu item does not 
allocate more room in this case. The block is simply reallocated to the same size, restilting in no 
change. Figure 14-12 shows the window's 2 cai after the “Do It!” menu item was clicked. 


/ 


\ 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam). | 
; Ce : : 


PAINTSTRUCT © ; Pps ; 

static HANDLE - hMem ; 

char FAR - - *pMem ; 

char . cBuf £128] ; 

int - i, nSize, nFlags ; 

switch (CiMessage) /* process windows messages */ 
a4 : : 


case WM_CREATE: , 
if ChMem = GlobalAlloc (GMEM_MOVEABLE, 27)) 


{ : 
if CpMem = GlobalLock (hMem)) 
¢ 
for (i =0; 7 < 26 5 i++) 
*pMem++ = 'A' + i 7 
*poMem = 0 >; 
GlobalUntock ChMem) ; 
ages 
else 
= MessageBox (hWnd, "Could not lock memory block.", 
“Memory Error", MB_ICONHAND | MB_OK) ; 
} : 
else 
{ d : 
MessageBox (hWnd, “Could not allocate memory", 
“Memory Error", MB_ICONHAND | MB_OK) ; 
DestroyWindow (hWnd) ; 
t > 
break ; 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
if (pMem = GlobalLock (hMem)) 
{ 


‘nSize = GlobalSize (hMem) ; 
nFlags = GlobalFlags (hMem) ; 
TextOut (ps.hde, 10, 10, cBut, wsprintf (cBuf, 
“The memory block is %d bytes in size.", 
nSize)) ; 
TextOut (ps.hdc, 40, 30, cBuf, wsprintf (cBuf, 
“Contains: Zs", C(LPSTR) pMem)) ; 
TextOut (ps.hdc, 10, 50, cBuf, wsprintf “CeBuf, 
“Flags: Discardable: %d, Lock Count: %d" 
nflags & GMEM L_DISCARDABLE, nFlags &. 
GMEM_| EOGREOUNT)2 2 
GlobalUnlock (hMem) ; 
} 
EndPaint ChWind, | &ps) ; 
break ; ; 
‘case WM_ COMMAND: /* process menu items */ 
switch (wParam) : “ 


case IDM_DOIT: _  /* User hit the "Do it" menu item */ 
if ChMem = GlobalReAlloc ChMem, 
(26 * 2) +.1, GMEM_MOVEABLE)) 
{ . : , 
if (pMem = GlobalLock (hMem)) 
C ae 


for (§ =0; i1-< 26; ; i++) 
*pMemt++ 7 /* skip old: stuff */ 
for (i =0; 1 < 26 3 i++) © 
*pMem++ = 'a' + i ; 
*pMem = 0 > 
GlobalUnlock ChMem) ; 


else 
MessageBox (hWnd, : - 
“Could not lock, memory block.“, 
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“Memory Error”, 
MB_ICONHAND | MB_OK) ; 


else 
MessageBox (hWnd, 
"Could not re-allocate memory", 
“Memory Error", MB_ICONHAND | MB_OK) ; 
InvalidateRect (hWnd, NULL, TRUE) ; /* force paint */ 
break ; . 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ;° 
} 
break ; 7 
case WM_DESTROY: : /* stop application */ 


GlobalFree ChMem) ; 
PostQuitMessage (0) ; 


break ; 
default: /* default windows message processing */.- 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
} 
GropaLCompact eWin2.0 eBWin30 mWin3.1 
Purpose Compacts memory in the global heap, and determines the size of the largest available memory 
area, 
Syntax DWORD GlobalCompact(DWORD dwMinFree); 
Description GlobalCompact() first compacts the global memory heap by moving all moveable blocks together, 
If dwMinFree bytes of contiguous memory are not available after compacting, GlobalCompact() 
discards blocks. This continues until either the requested memory space is available, or until no 
further discardable memory blocks can be found. 
Uses " Use this function any time a series of memory blocks is allocated and freed. Use of GlobalCompact 
assures that the largest possible memory block is made available if needed. 
Returns DWORD, the number of bytes in the largest available block of free memory in the global heap. 
See Also GlobalAlloc(), GlobalReAlloc(), GlobalFree() 
Parameters . 
dwMinFree DWORD: The number of bytes of contiguous memory desired in the global heap. IfdwMinFree is 
zero, GlobalCompact() returns the size of the largest block of global memory that can be re- 
turned if all discardable segments are removed. . 
Caution If the returned value is used as the dwBytes parameter for ohare: do not use the 
GMEM_NOCOMPACT or GMEM_NODISCARD flags. eS EE a 
_ Related Messages WM_COMPACTING Dolt! Quit 
Block 0's address Js 0x188d0000. 


aaa Block 1's address is 0x18ad0000. 
four blocks of global memory, each 1,024 bytes in size. Block 0 Block 2's address is 9x18850000, 


is moveable, block 1 is moveable and discardable, block 2 is | Block 3's address Is 0x187d0000. | 


Example This example, which is illustrated in Figure 14-13, allocates 


Free Memory = 851934 


moveable, and block 3 is fixed. When the user clicks the “Do 
It!” menu.item, the application discards block 1. This does not Figure 14-13. Global- 
increase the size of the !argest available block of memory be- Compact() Example. 
cause the fixed block number 8 gets in the way. , 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 

PAINTSTRUCT ps ; 

static HANDLE hMem [4] ; 


633: 
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dwBytes 


cnet cBuf £128] ; 
ihe. LP TR pMem C41; 
int i 
DWORD dwFree ; 
switch (iMessage) aia /* process windows messages */ 
{ 
case WM_CREATE: 
hMem COJ = GlobalAlLloc (GMEM_MOVEABLE, 1024) ; 
‘hMem C1] = GlobalAlloc (GMEM_MOVEABLE | 
GMEM_DISCARDABLE, 1024) ; 
_hMem C2] = GlobalAlloc (GMEM_MOVEABLE, 1024) ; 
hMem C3] = GlobalAlloc (GMEM_FIXED, 1024) ; 
break ; 
case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
for ese ee Pte) ates 
{ 
pMem [Lil = GlobalLock (hMem Cid) ; 
TextOut (ps.hdc, 10, 20 * i, But, wsprintf CcBuf, 
"Block %4d's address is Ox%lx.", i, pMem cia); 
GlobalUntock ChMem Cid) ; : 
} Pa) 
dwFree = GlobalCompact (0) ; ye find free ee */ 
TextOut (ps.hdc, 10, 80, oanes MSPP Ines (cBuf 
“Free Memory = 4Li", duFree)) + 
Engr adit (hWnd, ied ‘ 
break ; 
case WM_COMMAND: Tt process menu items */ 
switch (wParam) : 
{ : i 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
GlobalDiscard (hMem £1]) ; 
InvalidateRect (hWnd, NULL, TRUE) ; /* force paint */ 
break ; ee 
case IDM_QUIT: /* send end of Seplicaeien message */ 
for GG =O; 54<4,5 i ++) : . 
= ‘GlobalFree clone Cid) ; 
DestroyWindow (hWnd) ; 
‘break ; : 
} 
break ; ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; : 
break ; 
default: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; , 
} 
return (OL) ; 
} 
GiopaLtDosALLoc = BWin2.0 eWin30 m@Win3.l 
Purpose Allocates a memory block that can be accessed by both DOS and Windows. 
Syntax - DWORD GlobalDosAlloc (DWORD dwBytes); 
Description . _The memory block allocated will be in the first megabyte of linear address space. \ 
Uses. ) Not normally used. Can be used to allocate memory for device drivers that will be accessed by MS- 
DOS applications. Using this function reduces Windows’ ability to optimize memory usage. 
Returns ~ DWORD. The high-order word contains the paragraph segment for the memory block (real-mode 
memory address). The low-order word contains the selector (protected-mode memory address). 
See Also GlobalAlloc(), LocalAlloc(), GlobalPageLock() 
Parameters ; A ge 
DWORD: The number of bytes to be allocated. 


’ 
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Example ' ‘This example (courtesy of Mark Peterson) demonstrates allocating a block of memory that can be 
accessed by either Windows or DOS. In this case, only Windows uses the block. The block is also 
page-locked, forcing it to remain in the same physical address and stopping a any y possible writing 
of the data to virtual (disk) memory. The address does not ree 
change when GlobalCompact() is called (user clicks the “Do 
It!” menu item). Figure 14-14 shows how the returned value _[Conteins: ACDEFGHUKLMNOPORSTUWWKYZ 
translates into the selector and segment values. A Windows far ae See We es alee 
pointer is the selector value in the high-order word. DOS in ; 
real mode (and Windows in real mode) uses the simple seg- Figure 14-14. 


ment value to point to the memory block. ' GlobalDosAlloc() Example. 
Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 
PAINTSTRUCT ps ; 
DWORD dwValue-; ee 
static WORD wSegment, wSelector ;. 
static LPSTR WindowsPtr ; 
LPSTR pWind ; 
static void far *DosPtr ; 
char cBuf €128] ; 
int i, nLockCount ; 
switch (iMessage) -/* process windows messages */ 
{ " 
case WM_CREATE: ‘ ; 
dwValue = GlobalDosAlloc (27) ; /* allocate mem block */ 
if CdwValue) /* demonstrate selector/segment */ 


/* show eacts of returned value */ 
wSegment = HIWORD (dwValue) ; 
wSelector = LOWORD (dwValue) ; 2 
WindowsPtr = CLPSTR) MAKELONG (O, wSelector) ; 
DosPtr = (void far *) MAKELONG (0, wSegment) ; / 
/* page Lock it */ 


nLockCount = GlobalPageLock (wSelector) ; / 
if (nLockCount) 
{ 


pWind = WindowsPtr ; 

for (i =0; i < 26; i++) 
*pWind++ = 'A' +1; 

*pWind =0; 


} 
break ; 
case WM_PAINT: 
: BeginPaint (hWnd, &ps) ; 
TextOut (ps.hdc, 10, 0, cBuf, wepr net CcBuf, 
“Contains: 4s", WindowsPtr)) ; 
TextOut (ps.hdc, 10, 20, cBuf, wsprintf (cBuf, 
“Segment = Ox%x, selector = Ox%x" 
wSegment, wSelector)) ; 
TextOut (ps.hdc, 10, 40, cBuf, yearned (cBuf, 
“DosPtr = Oxdlx, WindowsPtr = Ox%lx, ", 
: -DosPtr, WindowsPtr)) ; 
” 3 : ov EndPaint Chlnd, &ps) é 
yoo break ; ° ss 
case WM_. COMMAND:. ; 7 /* process menu items */ 
switch (wParam) ; : 


case IDM_DOIT: aa User hit the “Do it" menu item */ 


GlobalCompact (0) ; /* try to budge it */ . 
InvalidateRect chunds NULL, TRUE) ; /* force. paint */ 
break ; 
case IDM_QUIT: —  |® “ooo end of Sppevestion message */ 
DestroyWindow (hWnd) ; 


break ; 


WOR oe 
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_ Example 


} 
break ; 
case WM_DESTROY: /* stop application */ 
nLockCount = GlobalPagéUnlock swSelector? ; 
wSelector = GlobalDosFree (wSelector) ; 
if (wSelector) 
MessageBox (hWnd, “Did not free memory block.", 
"GlobalDosFree() Error", MB_OK) ; 
PostQuitMessage (Q) ; 


b k ; 3 
default: ee /* default windows message processing-*/ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
‘ 
return (OL) ; 

} 4 

GLOBALDOSFREE _ ; Win2.0 mWin30  mWin31 

Purpose Releases a block of memory allocated with GlobalDosAlloc(). . 

Syntax WORD GlobalDosFree (WORD wSelector); 

Description Memory blocks allocated with GlobalDosAlloc() inhibit memory optimization by Windows. 
GlobalDosFree() should be called as soon as possible to reiease the memory blocks. 

Uses Memory blocks allocated by GlobalDosAlloc() are accessible by both Windows and real-mode 
. DOS applications. 

Returns WORD, NULL if the function was successful. Equal to wSelector on error. 

See Also GlobalDosAlloc(), GlobalPageLock(), GlobalAlloc() 

Parameters 

wSelector WORD: The selector returned in the low-order word of the returned DWORD when GlobalDos- 
Alloc() was called. This is the selector value for the memory block. 

Example | See the example under the GlobalDosAlloc() function description. 

GLOBALDISCARD _ __wWin2.0  Win3.0  mWin3l 

' Purpose Discards a memory block from the global heap. 
Syntax HANDLE GlobalDiscard(DWORD hMem); . 
Description -Discarding a memory block makes the space available for allocating other blocks of memory. The 
_hMem handle remains usable after the block is discarded, although it does not point to active 
memory. hMem can be reused by using GlobalReAlloc() to allocate another block of memory. 
Only blocks allocated with the GMAEM_DISCARDABLE and GMEM_MOVEABLE flags set can be 
discarded. 

Uses — Discarding memory to make room for other blocks. Note that GlobalFree() removes the memory 
block and invalidates the memory handle. GlobalDiscard() just discards the memory block, put 
the hMem handle remains valid. 

Returns ~ HANDLE. Equal to hMfem if the function was successful, NULL on error. 

See Also GlobalFree(), GlobalReAlloc() 

Parameters re 

-hMem HANDLE: The handle to the discardable memory block. This i is the value returned by Global- 
Alloc() when the block was first allocated. 


See the previous example under GlobalCompact(): 
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Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
hMem 


Example 


in Figure 14-15, this does not stop the block from being paged 
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OWin2.0 aWind.0 wWin3.1 
Stops a memory block from being moved in memory. 
void GlobalFix (HANDLE hMem); 


When Windows is operating in Standard or 386 enhanced mode (not real mode), locked memory 
blocks can be relocated in linear memory. This does not invalidate far pointers to the block used 
within the program, but will change the physical address ofthe fz ROR REE Henee ees TS Co 
block in memory. Calling GlobalFix() prevents the global 


memory block from being moved in linear memory. As shown _| The memory block is 32 bytes in size. 
Contains: ABCDEFGHUKLMNOPGRSTUVWXYZ 
Flags: Discardable: 0, Lock Count: 1 

Handle = OxbJe, Address = Oxb3d0008 


to disk as virtual memory. Use GlobalPageLock() to stop vir- 
tual memory writes for a memory block. Each time GlobalFix() Figure 14-15. GlobalFix() 
is cailed, the block’s lock count is increased by one. Anequal Example. 

number of GlobalUnfix() calls is required to free the block. 


Not often used. Used with (old) drivers that assume a fixed-memory address. Fixing a enor 
block reduces Windows’ ability to optimize memory use and should be avoided. 

No returned value (void). 

GlobalUnfix(), GlobalLock(), GlobalPageLock(), GlobalAlloc() 


HANDLE: The global memory block’s handle. This is the value returned by GlobalAlloc(). 


This example, initially allocates a moveable global memory block big enough to hold 27 bytes. The 
uppercase alphabet is written to the memory block. The block is then fixed in memory by calling 
GlobalFix(). Clicking the “Do It!” menu item causes the GlobalCompact() function to be called... 
This has no effect on the memory block’s address, as it is fixed. The memory block is unfixed and 
deleted when the application terminates. _ 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


PAINTSTRUCT ps ; “ ‘ 
Static HANDLE hMem ; 

Static LPSTR pMem ; 

LPSTR ; pMemTemp ; 

char cBuf [128] ; 

int i, nSize, nFlags ; 

switch (iMessage) /* process windows messages */ 


t 


case WM_CREATE: 
hMem = GlobalALloc (GMEM_MOVEABLE, 27) ; 
pMemTemp = pMem = GlobalLock (hMem) ; 
for (i =0 7; 1 < 26 ; i++) 


*pMemTempt+ = 'A' + 7; 
*pMemTemp = 0; - 
Global Fix ChMem) ; /* fix block in memory */ 


break ; ee 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
nSize = GlobalSize (hMem) ; 
nFlags = GlobalFlags (hMem) ; 
TextOut (ps.hde, 10, 10, But, wsprintf (cBuf, 
"The memory block is 4d bytes in size.", nSize)) ; 
Textout (ps.hdc, 10, 30, cBuf, wsprintf (cBuf, 
“Contains: Xs", (LPSTR) pHem)) ; 
TextOut (ps.hde, 10, 50, cBuf, wsprintf “CcBut, 
“Flags: Discardable: “%d, Lock Count: ud", 
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“nFlags ‘& GMEM_DISCARDABLE, alee & GMEM_| LOCKCOUNT)) ; 
Textout (ps.hdc, 10, 70, cBuf, wsprintf (cBuf, 

“Handle = Ox%x, Address = ONeNE hem, pMem)) ; 
EndPaint ChWnd, Gps) 7 : 
break ; 


case WM_ COMMAND: '/* process menu items */ 
switch (wParam) ; 
{ . 
case IDM_DOIT: : on User hit the "Do it" menu item */ 
es GlobalCompact (0) ; /* try to budge it */ 
TnvalidateRect Chivad, NULL, TRUE) ; . [* force paint */ 
break ; 
case -IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; : 
: break ; 
oo. = } 
— break ; 
case WM_| DESTROY: /* stop application */ 


} 
_ return ¢ 
} 


GLOBALF LAGS 
Purpose 
Syntax 
Description 


GlobalUnfix ChMem) ; 
GlobalFree C(hMem) ; 
' PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing <a = 
return DefWindowProc (hWnd, MBSEOAg SY Brera lParam) ; 


OL) ; aeeae 


aWin2.0 mWin30 wWin31 


_ Determines if a memory block in the global heap is locked, discarded, or potentially discardable. 


WORD GlobalFlags(HANDLE hMem); mes ee 


This function checks the status of a memory block allocated in the global heap. If a memory block 
is locked with GlobalLock() more than once without calling GlobalUnlock(), the block’s lock 
count will be more than one. GlobalUnlock() will have to be called:as many times as the lock 
count to unlock the memory area. Memory blocks can*be discarded using GlobalDiscard() and 
still have valid handles. GlobalFlags() will determine if the memory. block has been discarded, or 
if it was allocated using the LMEM_DISCARDABLE flag. 


To check the validity of a memory salsa or to check if a memory block has been locked more 


than once. 
WORD. The high-order byte contains one of the flags in Table 14-4, 


GMEM ’DDESHARE 


The block can be shar oa iby other Api This | is be used with Sout data eee 


GMEM_DISCARDABLE The block was allocated with the GMEM_DISCARDABLE flag. 
GMEM_DISCARDED The block has been discarded. The GlobalReAlloc() function will need to be called to.make the 
| * 8 . memory area usable. 
. GMEM_NOT_BANKED " The block cannot be banked, ‘This only applies to EMS memory banking systems. 


Table 14-4. GlobalFlags() Flags. 


See Also. 


The low-order byte contains the lock-count of the memory block. Combine the returned word 
with GMEM_LOCKCOUNT using the C language binary and ampersand (&) to determine the 
lock-count. 


| tobal nee; GlobalSizeQ), CoblLackQ 
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Parameters 

hMem HANDLE: The handle to the global memory block returned- by GlobalAlloc(). 

Example See the example under GlobalAlloc(). 

GLOBALF REE eWin20 mWin3.0 mWin31 

Purpose Frees a block of memory allocated in the global heap. 

Syntax HANDLE GlobalFree(HANDLE hMem); 

Description Freeing a memory block returns the memory to the system for reuse. All memory blocks allocated 
within an application should be freed before the application exits to return the memory to Win- 
dows. 

Uses There should be a call to GlobalFree() for every call to GlobalAlloc() i in a program, 

Returns ; HANDLE, equal to hMem if the memory block was freed. NULL on error. 

See Also GlobalAlloc(), GlobalDiscard(); GlobalReAlloc() 

Parameters 

hMem HANDLE=The handle to the memory block allocated in the local heap with GlobalAlloc(). 

Example See the-example under plobalanoed: 

GLOBALHANDLE © | mWin20 m@Win3.0 ‘sWin3.l 

Purpose Returns the handle of a global memory block given its address. 

Syntax DWORD GlobalHandle(WORD wMem); 

Description Returns the handle of the memory block given the segment address (or selector) of a block of 
memory in the global heap. This is the reverse of the normal procedure of getting the address of 
a memory block by using GlobalLock() to lock a block using the memory block handle. 

Uses This is useful in cases where locked (fixed) memory blocks are used. With locked blocks, the. 
address does not change, so it is efficient to store only the block’s address and not store the 
handle. GlobalHandle() can be used to retrieve the handle if it is needed to free the block. 

Returns DWORD. The low-order word contains the handle of the global memory block. The high-order 
word contains the segment address of the memory block. Returns NULL on error. 

See Also _GlobalFlags() 

Parameters 

whem WORD: An unsigned integer value. This is the segment address of the global memory block. 

Example See the example under GlobalFix(). 

GLoBpaLLock mWin2.0 mWin30 mWin3l 

Purpose ‘Locks an allocated memory block in the global heap. oy 

Syntax LPSTR GlobalLock(HANDLE hMem); | y 

Description Moveable memory blocks allocated with GlobalAlloc() must be locked before data can be written 
or read from the memory area. The block should be unlocked with GloballInlock() as soon after 

- use as possible. 

Uses . Used to “realize” a memory pointer. This means that the return value is a far pointer to a block of 
memory. The pointer will remain valid until the block is unlocked with GlobalUnlock(). 

Returns | ~ LPSTR, a far pointer to the beginning of the Mewar area. 

See Also GlobalUnlock(), GlobalAlloc() . 


—_— 
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Parameters — 
hMem HANDLE: A handle to the memory area allocated with GlobalAlloc(). 
Example See the example under ‘GlobalAlloc(). 
GLoBALLRUNEWEST  wWin0) gs Win3.0 mm Win3.! 
Purnose _ Marks a memory block to be the last one to be discarded in the global heap. 
Syntax HANDLE GlobalLRUNewest(HANDLE hMem); 
Description Windows keeps track of discardable memory blocks. Normally, the most recently used blocks are 
the last to be discarded if Windows runs short of memory. GlobalLRUNewest() allows the applica- 
tion to specify a memory block that should be the last one discarded if the global heap is com- 
pacted. This function is called internally by Windows whenever GlobalLock() or GlobalWire() is 
called. The LRU position is also used to determine if a memory block should be located in virtual 
memory (in 886 enhanced mode). 
Uses Used to optimize an application’s performance if a number of discardable memory blocks are 
used. This is the ideal way to keep a memory block available for immediate access without locking 
/ it in memory, or using the GMEM_NODISCARD attribute. 
Returns HANDLE. Returns hMem if the function was successful, NULL on error. 
See Also GlobalLRUOldest(), GlobalCompact() 
Parameters , 
hMem HANDLE: The global memory block handle. This is the value returned by GlobalAlloc() or 
. GlobalReAlloc() the last time the memory block was allocated or resized. 
Related Messages WM_COMPACTING . 
Example — This example, whichisillustratedin eS — om: lhl dal 


Figure 14-16, allocates two memory 
blocks on the local heap. Both are 
moveable and discardable. When LockCount = 0, Discardable = 1} | LockCount = 0, Discardable = 1 
the user clicks the “Do It!” menu hMemz2 size: 10240 | hMem2 size: 0 

item, the first block is marked with LockCount = 0, Discardable = 1 LockCount = 0, Discardable = 1 
GlobalLRUNewest(), and the sec- Figure 14-16. GlobalLRUNewest() and Global- 

ond is marked with GlobalLRU- LRDOMaest ) Example. 

Oldest(). This makes the second 

block the most likely to be discarded. Requesting a contiguous enlaibig space slightly larger than 
the amount available on the global heap with GlobalCompact() forces a block to be discarded. 
Only the second memory block ends up discarded. Note that the second memory block's handle 
and status (flags) remain valid. The block can be restored with GlobalReAlloc(). 


hMemt! size: 10240 hMem!1 size: 10240 


long FAR PASCAL winder CHWND hWnd, unsigned ote WORD wParam, LONG lParam) 
{ 


| tafe 
PAINTSTRUCT i]; 
static; HANDLE ;— lies hMent, hNen2 ; 
char eee cBuf [128] ; 
int iv. nFlags1, nFlags2 ; 
DWORD dwFree, dwSize1, dwSize2; 
‘ switch CiMessage) : ' /* process windows messages */ 


case WM_CREATE: , 
‘hMem1 = GlobalAlloc (GMEM_MOVEABLE | 
GMEM_DISCARDABLE, 10240) ; 
“hMem2 = GlobalAlloc (GMEM_MOVEABLE | 
GMEM_DISCARDABLE, 10240) ; 
if (!hMem1-|| !hMem2) 
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{ a 
MessageBox (hWnd, ; 
. "Could not allocate memory blocks.", 
“Memory Error", MB_ICONHAND | MB_OK) ; 
DestroyWindow (hWnd) ; 
} eae 
break ; 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 


nflags1 = GlobalFlags (hMem1) ; 
nFlags2 = GlobalFlags (hMem2) ; 
dwSize1 = GlobalSize (hMem1) ; 
dwSize2 = GlobalSize (hMem2) ; 


TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
“hMem1 size: “Li", dwSize1)) ; 

TextOut (ps.hdc, 10, 30, cBuf, wsprintf (cBuf, 
“LockCount = %d, Discardable = %d", 
nFlags1 & GMEM_LOCKCOUNT, 

(nFlagsi & GMEM_DISCARDABLE ? 1: 0))) ; 

TextOut (ps.hdc, 10, 50, cBuf, wsprintf (cBuf, 
"hMem2 size: %Li", dwSize2)) ; 

TextOut (ps.hdc, 10, 70, cBuf, wsprintf (cBuf, 
“LockCount = %d, Discardable = %d", 
nFlags2 & GMEM_LOCKCOUNT, 

(nFlags2 & GMEM_DISCARDABLE ? 1: 0))) ; 

EndPaint (hWnd, &ps) ; 

break ; 

case WM_COMMAND: /* process menu items */ 
switch (wParam) ; 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
GlobalLLRUNewest (hMem1) ; ' /*® only one of these */ 
GlobalLRUOldest (hMem2) ; /*' two calls is needed */ 
dwFree = GlobatCompact (0) ; /* check free space */ 
GlobalCompact (dwFree + 64) ; /* force discard */ 
InvalidateRect (hWnd, NULL, TRUE) ; /* force paint */- 
break ; 

‘ case IDM_QUIT: . /* send end of application message */ 

DestroyWindow (hWnd) ; 
break ; : 

} 

break ; 

case WM_DESTROY: ; /* stop application */ 

GlobalFree (hMem1) ; 

GlobalFree (hMem2) ; 

PostQuitMessage (0) ; 


b k ; ; 
default: ae /* default windows sessage processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} - 
return (OL) ; 
GLOBALLRUOLDEsT mWin2.0 mWin30 mWin3.1 
Purpose Marks a memory block to be the first one to be discarded in the global heap. 
~ Syntax HANDLE GlobalLRUOldest(HANDLE hMem); 
- Description Windows keeps track of discardable memory blocks. Normally, the most recently used blocks are 
: the last to be discarded if Windows runs short of memory. GlobalLRUOldest() allows the applica- 
tion to specify a memory block that should be the first one discarded if the global heap is com- 
pacted. ane : 
Uses Used to optimize an application's performance ifa number of discardable memory blocks are 


‘used. This function and GlobalLRUNewest() are the ideal way to prioritize which memory blocks 


should be available for immediate access without locking it in memory, or using the 
GMEM_NODISCARD attribute. 


641 
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Returns 


Parameters 
. hMem 


HANDLE Returns hMem if the tc success, NULL: on error.- 
Global LRUNewest) GlobalCompact()y 


HANDLE: The global memory block bandib, This ts the value returned by GiobatAttoco Or. 


GlobalReAlloc() the last time the memory block was faltocated or resized. f 


Related Messages WM_COMPACTING 


_ pNotifyProc 


Related Midas WM COMPACTING ; 


Caution — 


Example 


ing messages via the message loop before GlobalNotify() is 


Example ‘See the previous example under cba tNeres, 

GrosaLNotry Are - gWin20 mWin3.0 mWinat 

Purpose Installs a notification function, which | is called if global memory objects are about to be dis- 

ae carded. 
. Syntax void GlobalNotify(HANDLE IpNotifyProe); 
Description - Memory blocks allocated with the GMEM_DISCARDABLE and GMEM_ MOVEABLE fae can be: 
. discarded if Windows needs a larger memory space in the global heap than is currently available.’ . 
Normally, discarding is done on a most-recently-used-last-discarded basis, with no warning to the . 
application that allocated the block. Installing a notification function causes Windows to activate 
the function before any memory block is discarded. This provides an opportunity for the notifica- 
tion function to free a less critical memory block. Only blocks allocated with the GMEM_DIS- 
CARDABLE | GMEM_MOVEABLE | GMEM_NOTIFY flags will result in the notification function 
. .. being called. The notification function must be part of a DLL (Dynamic Link Library) with a fixed 
we 3 code segment. The DLL cannot use the calling application's stack. Even though the notification — 
; must be in a DLL, discarding money allocated by a DLL oe not result in the notification ae. 
a tion being called. 

Uses. Used in applications that allogate discardable memory block. 

Returns No returned value (void). 

See Also z= GlobalLRUOldest(), GlobalLRUNewest() 

Paranicters ge ; | a —_ 

.. HANDLE: The procedure-instance address of the notification function. This is the value returned” 


. by GetProcAddress(). The notification function must be defined in a DLL with a fixed-code ses: 


ment. The notification function must have the following form: 


_- _ BOOL FAR PASCAL NotifyProc (HANDLE kMem); 


where hMem is the handle to the block being discarded. The notification function should return 
nonzero if Windows should discard the block, zero if the block should not be discarded. 


The notification function will continue to be called unless the situation causing Windows to 


discard the memory block is changed. Typical actions within the notification function include 


- discarding some other block of memory, eliminating the need to discard the block whose handle. 
.is hMem. The callback. function should not call any pm which may cause relocation of | 


memory objects (GlobalAlloc(), GlobalReAlloc()). 


Notification functions cannot be installed while processing the 
WM_CREATE message. The calling program must be process- 


called. This function can only be:called once ber aie 


- instance. LockCount = 0, Discairdable =1 “if. 
"_ This example sets up.a notification. seams to- warn: aa “Figure 14-17, GlobalNot; i .): Sees 


memory blocks are about to be discarded. All the notification anen 
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t> NOTIFY.DEF Definition File for DLL 


LIBRARY 
DESCRIPTION 
EXETYPE 
CODE 

DATA 
HEAPSIZE 

_ EXPORTS 


procedure does is put a message box on the screen warning that memory is about to be deleted. 


After the memory has been deleted, the window appears as shown in Figure 14-17. 
' The notification must reside in a Dynamic Link Library (DLL) with a fixed code segment. The 
code segment is fixed by specifying the “FIXED” attribute in the DLL’s definition file. The wo: 


functions called from outside the DLL are listed in the EXPORTS section. 
/ 


NOTIFY 

'dll for notification’ 
WINDOWS 

PRELOAD FIXED 

PRELOAD FIXED SINGLE 
1024 

NotifyFunc 

SavehWnd ~ 


The notification function has a standard format (described above). In order to use the 
MessageBox() function from within the DLL, the DLL must use a second function , SavehWnd(), : 


to just store the calling window’s handle. 


The notification fun ction NotifyFunc() shown here is only an outline. A useful notification 
function would ins stile action to avoid discarding a memory block, such as discarding the least 
important block. Note that no local variables are used. Notification functions cannot assume the 
stack segment of the calling program, as they aré called from Windows’ memory management logic. 


© NOTIFY.C C Source Code for Notification Function DLL 


Aaipotity. c¢ memory discard notification functions */ 


Hinclude’ <windows. h> 


static 


HANDLE hWindow = NULL ; 


int FAR PASCAL LibMain (HANDLE hinstance, WORD apereress word wHeapSize, | 
LPSTR LpszCmdLine) °c , 


if (wHeapSize > 0) 


; UnlockDbata (0) ; 


‘feturn (1) ; 


+ 


void ia PASCAL SavehWnd (HANDLE hWnd) - 


| hlWindow = hind ; 


\ 
‘ 


Bool FAR PASCAL NotifyFunc (HANDLE hMem) 


static intn; 


4 ChWindow == NULL) 


else 
§ 


> 


so 


return (1) ; 


MessageBeep (0) ; ' %¢* forgot to run SavehWnd - just beep */ 


ne MessageBox ChWindow, "Memory About To Be biscarded.", 
“Warning”, MB_ ICONASTERISK | MB_OKCANCEL) ; 


aif (n= = IDCANCEL), 
a © 


' /* delete some other block of memory here *f 
return (0) 5 - 
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© NOTIFY NMAKE File for NOTIFY. DLL 


The NMAKE file for the DLL file shown here includes the debugging switches. The key ¢ differ- 
ence when compiling DLLs is that the stack segment and data segment are not the same ae 
switch with the Microsoft compile). te : aes 


/ 
ih 


a make file for. notify library 


“ALL: notify.dLl 


CFLAGS=-c —D LINT_ARGS -ASw -Zip -0d -Gsw -W2 
_LFLAGS=/NOD /co peana anne 


“notify. obj: 
$(cc) $ (CFLAGS) notify.c 


“notify: dtl: 


notify.c 


notify.obj notify.def 


Link SCLFLAGS) notify libentry, MORITY = dll, NUL, Libw sditcew, notdty 


re notify. dlt 


- The main program’s header file (GENERIC.H) must include friction prototypes of the two 
exported functions. The program’s definition file must also list them in the IMPORTS section. 


oO GENERIC. DEF Module-Definition File for GENERIC.C | 


NAME 
DESCRIPTION 


EXETYPE 


STUB 
CODE 


DATA © 
-HEAPSIZE 


STACKSIZE 


EXPORTS 
IMPORTS 


GENERIC 
"generic windows program! 

WINDOWS 

"WINSTUB.EXE' 

PRELOAD MOVEABLE 

PRELOAD MOVEABLE MULTIPLE 
1024 

5120 


.WndProc 


NOTIFY.NotifyFunc 
NOTIFY. SavehWnd 


3 The main program sets up two global memory blocks on startup. Both are discardable. When . 
WM_PAINT messages are received, the size and status of the two blocks are written to the 
window's client area. The notification function is not installed until-the user clicks the “Do It!” 
menu item for the first time. First SavehWnd() is called to give the DLL the main window's 
handle. Then GlobalNotify() is called to set up the notification procedure. The notification proce- 
dure can only be set up once per program instance, so a static Boolean variable, bSetNotify, is 


t 


-. used to stop GlobalNotify() from beizg called twice. Discarding global memory is forced by. call- 


‘ing GlobalCompact(), requesting a memory block larger than the largest available block. At this 


point in the program's execution, the notification function is called by Windows. NotifyFuncQ) 
displays the message box. 


C GENERIC.C Program Extract of Only WndProc() Function 
die ‘FAR PASCAL WndProc CHWND hWnd, yns Toned iMessage, WORD wParam, LONG lParam) 


PAINTSTRUCT ; ps ; 

static HANDLE hMem1, hMen2 ; 
char - ' eBuf (128) ; 

int nFlagsi, ae taaeets 


. static 


DWORD. dwFree, dwSizet, dwSized ; 
static FARPROC fpNotify ; - 
BOOL = bSetNotify = FALSE ; 
eee CiMessage) /* process windows messages */ 


case WM_CREATE: a 
hMem1 = GlobalAlloc (GMEM_MOVEABLE | 


__GMEM_DISCARDABLE |_GMEM_NOTIFY, 10240) 7-02. 
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hMem2 = GlobalAlloc (GMEM_MOVEABLE | ° 
GMEM_DISCARDABLE | GMEM NOTIFY, 10240) ; 
if CthMem1 [| !hMem2) 

{ 


MessageBox (hWnd, 
“Could not allocate memory blocks.", 
“Memory Error", MB_LICONHAND | MB_OK) ; 
DestroyWindow (hWnd) ; 
} 
break; EF 
case WM_PAINT: S: - 
BeginPaint (hWnd, &ps) ; 


nFlags1 = SlobalFlags (hMem1) ; 

nFlags2 = GlobalFlags ChMem2) ; . 

dwSize1 = GlobalSize (hMem1) ; 

dwSize2 = GlobalSize (hMem2) ; 7 


TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
: “hMem1 size: “ZLi", dwSize1)) ; 

TextOut (ps.hdc, 10, 30, cBuf, wsprintf (cBuf, 
“LockCount = 4d, Discardable = 4d", 
nFlags1 & GMEM_LOCKCOUNT, 

(nFlags1 & GMEM_DISCARDABLE 2? 1: 0))) ; 

TextOut (ps.hdc, 10, 50, cBuf, wsprintf (cBuf, 

- “hMem2 size: 2Li", dwSize2)) ; 
TextOut (ps.hdc, 10, 70, cBuf, wsprintf (cBuf, 
oe “LockCount = 4d, Discardable = 4d", 
nFlags2 & GMEM_LOCKCOUNT, 
(nFlags2 & GMEM_DISCARDABLE ? 1: 0)))-; 

EndPaint (hWnd, &ps) ; 

break ; 

' . ¢ase WM_COMMAND: /* process menu items */ 
switch (wParam) : aoe 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
if (!bSetNotify) 
{ 


bSetNotify = ERUES? . 

SavehWnd ChWnd) ; 

hModule = GetModaleHandle Cnotify") ; ; 

fpNotify = GetProcAddress ChModule, 
“NotifyFunc") ; 

GlobalNotify (fpNotify) ; 


} 
dwFree = GlobalCompact (0) ; /* check free space */ 
GlobalCompact (dwFfree + 64) ; /* force discard */ 
InvalidateRect ChWnd, NULL, TRUE) ; /* force paint */ 
break ; : 

case IDM_QUIT: {* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 

} 

break ; 

case WM_DESTROY: : /* stop application */ 


FreeProcInstance CfpNotity) 3 

GlobalFree (hMem1) ; 

default: /* default windows message processing */ - 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 


} 
return (OL) ; 


} : 

GiopaLPaceLocx | i | mWin20 mWin30 mWin3.1 

Purpose Stops a memory block from. being moved in linear memory, or from being written to disk (virtual 
| memory inhibited). . 

Syntax | WORD GlobalPageLock CHORD wSelector); 


WINDOWS AP! BIBLE - 


af. 


Although pointers to locked memory blocks remain valid, the block may still be moved in physical 


: Description os 
‘ ~ memory. Locked memory blocks can also be temporarily written to disk as virtual memory stor- 
age. Calling GlobalPageLock() physically locks down a memory block. The block will not be 
moved and will not be. written to virtual (disk) space. Each call to GlobalPageLock() increases 
‘the memory block’s lock-count by one. An equal number of calls to GlobalfageUnlookt) t is re- 
a quired to unlock the memory block. - 
- Uses’ 5 Normally not used. Page-locked memory blocks inhibit Windows’ ability to ‘pilaiss memory use. 
Page-locked blocks may be needed for device drivers and interrupt driven routines thatexpectto 
oe . write to a fixed address in real address space and that need rapid response. 
Returns _ WORD, the page- -lock-count. Returns zero on error. 
See Also — GlobalPageUnlock(), GlobalDosAlloc() - 
Parameters 
wSelector WORD: The selector for the memory. ‘block. This is the protected-mode equivalent of an offset. 
ere See the example under the GlobalDesAlloc() function description. 
Ginka PAckUMOGk | Se mWin2.0 mWin3.0 @Win3l 
Purpose ’ Unlocks a memory block locked with GiobalPageLockQ. . , 
Syntax WORD GlobalPageUnlock (WORDwSelector); : 
Description . Each call to GlobalPageLock() for a given selector increases the page-lock-count by one. Calling 
GlobalPageUnlock() decreases the page-lock-count by one. An equal riumber of calls to 
GlobalPageUnlock() is required to unlock a memory block. . 
Uses Unlocking a memory block locked with GlobalPageLock(). Once unlocked, the block can be. 
oe " moved in linear memory and be paged to disk (virtual memory). 
\Returns WORD, the page- -lock-count: after the function operates. Returns zero on error. 
See Also GlobalPageLock(), GlobalDosAlloc() 
. Parameters - e . ee en tk 
wsSelector --WORD: The selector for the memory block. This is the protected-mode-equivalent of an offset. - 
Example ie the eam under the GlobalDosAlloc() function description. 
- GropatREALioc | | : @Win2.0 @Win3.0 e@Win3.l 
_ Purpose _ Changes the size and/or attributes of a global memory block. 
Syntax . HANDLE GlobalReAlloc(HANDLE hMem, WORD wBytes, WORD wF lags); 
Description When a memory block is allocated with GlobalAlloc(), it can be resized using GlobalReAlloc() as 
; needed to fit the program's « data needs. Discardable memory blocks use this function to restore 
aes the memory size block, 
' Uses Usually used to increase the size of a:data block as new items : are added. It can also be used to 
a change the memory attributes from moveable to fixed, etc. 
Returns © HANDLE, the handle of the resized memory block. Returns NULL on error. The returned Satie 
. will equal hMem unless the GMEM_MOVEABLE flag is set, or unless the block was reallocated 
. past a multiple of 64K (64K minus 17 bytes in standard a 
~ See Also — seal GlobalDiscard() 
Parameters 
—hMem HANDLE: The handle of the memory block in the local heap, initially allocated with LocalAlloc() 
dwBytes 


_ _ DWORD: The new size of the merry block. 
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wFlags WORD: The type of memory to reallocate. This should be one or more of the flags listed in Table 
14-5, combined with the C: language binary OR operator (1), Choose either GMEM_FIXED or 
GMEM. E MOVEABLE, and then combine the choige with other options: 


GMEM_DISCARDABLE varant that can be iscontel if Windows needs to ia room. Used sie with 


24 GMEM_MODIFY. 
: GMEM_MODIFY Specifies that the attributes of the memory block will be changed, not the memory block size. 
a ; . The dwBytes parameter \ will be ignored. 
GMEM_MOVEABLE Moveable memory. if wBytes is zero, this flag causes a previously fixed block to be freed, or a 


previously moveable object to be discarded. This only occurs if the block has nct been locked. 
if wBytes is nonzero and the hMem block is fixed, GlobalReAlloc() will move the block to a new 
fixed location. The means that the retumed value will not be the same as hMem. Use with 

“ GMEM_MODIFY to make a fixed memory block moveable. 


~ GMEM_NOCOMPACT a e ; Memory in the local heap is not compacted or discarded to make room for the resized memory 


a block: Ignored if GMEM_MODIFY is set. 
GMEM_NODISCARD ° Memory in the loca! heap is not discarded to make room for the resized memory block: Ignored 
Bah Os ___ if GMEM_MODIFY is set. 
GMEM_ZEROINIT _Snitiaas the new part of the allocated memory block to Zero. Ignored if GMEM MODIFY is set. 


| Table 14-5, Globalioe ) Flags. - = 


Caution . if the program's data segment is s defined as moveable in the .DEF file, calling LocalAlloe) may 
cause the data segment to move. This will invalidate any far pointers. 
- Example = -——See the example under GlobalAlloc(). 
_ GropatSve . mWin20 mWin30 mWin3.l 
‘Purpose Determines the size of a memory block allocated in the ie wove heap. 
" Syntax» DWORD GlobalSize(HANDLE hMem); 


_Deseription This function determines the actual number of bytes allocated in the global heap by GlotialAlloe() 
-and/or GlobalReAlloc(). The number of bytes may be slightly larger than the number requested, 
as global memory blocks are rounded upward to the nearest 32 bytes. — 


- Returns ’ DWORD, the actual size of the memory block in bytes. NULL if hMem is not a valid memory . 
handle. The return value is invalid if the memory block has been discarded. 

See Also GlobalFlags, GlobalAlloc() 7 
hMem  _—_—__—.:«x HANDLE: The handle of the global memory block. 
Example. _ See the example under GlobalAlloc(). 
GiopaLUnrrx : ‘is @Win2.0 wWin3.0 mWin31 
Purpose Frees a memory block fixed by GlobalFixQ).. — i 
Syatax - _ ’ BOOL GlobalUnfix (HANDLE hifem); 


Description =—_ Each call to GlobalFix() increases the memory block’s lock count by one. GlobalUnfix() ‘eanees 
the lock-count by one. An equal number of calls to eee is peauired to release the fixed 
: pais. block. . 
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Uses Used with GlobalFix() in applications that require a memory block to remain at the same sd cae 

tion in linear memory. Bas 
Returns BOOL. Zero if the lock-count decreased to zero (oe no JOnESE fret). Nonzero if the lock count 

is above zero. rn ae 
See Also GlobalFix(), GlobalAlloc 0 : 
Parameters 

hMem * HANDLE: A handle toa global memory block. This is the value returned by. Glotalnlloc() 
Example See the example under the GlobalFix() function descripbion: 
GLOBALUNLOCK - Windom Wind.0 m Win 3.1 


Description 
block with allocated with the GMEM_FIXED flag. Unlocked blocks can also be discarded, if they 
were allocated with the GMEM_MOVEABLE | GMEM_DISCARDABLE style. If a memory block is 
locked more than once without being unlocked, the block’s reference count will be more than 
one. GlobalUnlock() will have to be called the number of times specified by the reference count 
before the block can be moved or discarded. 
Uses Memory blocks should be unlocked as soon after being locked as possible. Doing so makes it 
possible for Windows to make maximum use of the memory space. _ 
Returns BOOL. Zero if the block’s lock-count.is zero (completely unlocked), nonzero if not. 
See Also GlobalLock(), GlobalAlloc() — : 
Parameters ‘; ‘ ud 
hMem HANDLE: The handle of the global memory block to unlock. This is the value initially returned by 
GlobalAlloc(). . 
Example See the example under GlobalAlloc(). 
GLOBALUNWIRE | - mWin2.0 mWin3.0 = mWin3.1 
Purpose Unwires a wired (locked) block in the global heap. 
Syntax BOOL GlobalUnWire(HANDLE hMem); | 
Description This function unlocks a block locked in low memory by GlobalWire(). If more ian one call to 
bape . GlobalWire(), GlobalLock(), or GlobalFix() has been made, the lock-count for the memory block 
will be greater than one. A matching number of calls to GlobalUnWire(), ee and 
GlobalUnfix() will be needed to unlock the memory block. 
Uses There should be one call to GlobalUnWire() for every callto 
- GlobalWire() in an application. gS generic: «fe [> 
Returns BOOL. TRUE if the segment is unlocked, FALSE if not. 
See Also GlobalWire(), GlobalLockQ), GlobalFixQ) hMem! Address: 0x15f50000_ 
LockCount = 0, Discardable = 1 
peremeters | oe hMem2 Address: 0x15fd0000 
hMem HANDLE: The handle of the global memory block to unwire. | | ockcount = 1, Discardable = 0 
This is the value returned by GlobalAlloc() or GlobalReAlloc() 
the last time the block was created or resized. "Figure 14-18. GlobalWire() 
Example This example, illustrated in Figure 14-18, allocates two blocks and GlobalUnWire(, ) . 


Unlocks a locked memory block in the global heap os ; 
BOOL GlobalUnlock(HANDLE hMem); > ~ 
Unlocks a memory block. Once unlocked, the memory block can be moved by Windows, unless the 


of memory in the global heap. When the user clicks the “Do It!” Example.- 
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menu item, the program “wires” the second block, eee it in low meMOry: The block is 
“unwired” when the program exits. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ : 


PAINTSTRUCT 
static 
LPSTR 

char 

int 


switch (iMessage) 
{ 


Ps ; 

HANDLE -  hMem1, hMem2 ; 
pMem1, pMem2 ; 
cBuf £128] ; 
nflagst, nFlags2 ; 


case WM_CREATE: 


hMem1 = GlobalAlloc (GMEM MOVEABLE | 
GMEM_DISCARDABLE, 10240) ; 


/* process windows messages e/ 


hMem2 = GlobalAlloc (GMEM ’ MOVEABLE, 10240) ; 


if CthMemi || !hMem2) : 
{ 


MessageBox (hWnd, 


"Could not allocate memory blocks." 
“Memory ErEOr's MB_ICONHAND y MB_! OK) ; 


DestroyWindow (hWnd) ; 
} 
break ; 


case WM_PAINT: 


case WM_COMMAND: 


case WM_DESTROY: 


BeginPaint (hWnd, &ps) ; 

nFlags1 = GlobalFlags ChMem1) ; 

nFlags2 = GlobalFlags ChMem2) ; 

if ((pMem1 = GlobalLock (hMem1)) && 
(pMem2 = GlobalLock ChMem2))) 

{ : 


Textout (ps.hde, 10, 10, cBuf, wsprintf (cBuf, 
“hMemi Address: OxZLx", 


pMem1)) ; 


TextOut (ps.hde, 10, 30, cBuf, wsprintf (cBuf, 
“LockCount = %d, Discardable = %d", 
nFlags? & GMEM_LOCKCOUNT, 

(nFlags1 & GMEM_DISCARDABLE ? 1 : 0))) ; 
_ TextOut (ps.hdc, 10, 50, cBuf, wsprintf (cBuf, 
“hMem2 Address: Ox%Lx", pMem2)) ; 

TextOut (gs.hdce, 10, 70, cBuf, wsprintf (cBuf, 
"LockCount = 4d, Discardable = %d", 
nFlags2 & GMER_LOCKCOUNT, 

(nFlags2 & GMEM_DISCARDABLE ? 1: 0))) ; 


GlobalUnlock ChMem1) ; 
GlobalUnlock ChMem2) ; 
} P 
EndPaint (hWnd, &ps) ; 
break ; 


_/* process menu items */ 


N 


switch (wParam) s 

{ : 

case IDM_DOIT: /* User hit the "Do it" menu item */ 
nFlags2 = GlobalFlags (hMem2) ; 
if (!(nFlags2 & GMEM_LOCKCOUNT)) 

GlobalWire (hMem2) ; 

InvalidateRect (hWnd, NULL, TRUE) ; /* force paint */ 
break ; 

case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 

} 

break ; 


GlobalLUnWire (hMem2) ; 
GlobalFree (hMem1) ; 
GlobalFree (hMem2) ; 
PostQuitMessage (0) ; 
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/* stop application */ 


_ WINDOWS API BIBLE 


_ break ; . 
‘default: . /* default windows message processing */ 
return DefWindowProc Chiind, iMessage, wParam, lParam) ;° 


} 5 
return (OL) ; 
oe | 
GLosALWirE | mWin2.0 mWin30 mWindt 
Locks a global memory block in low memory. 
LPSTR GlobalWire(HANDLE hMem); 


This is similar to GlobalLock(), except that Windows attempts to move the memory block intolow — 
. Memory before the block is locked. This reduces the impact of mene a fixed block in the middle 
of the global heap. 


GlobalWire() is preferable to GlobalLock() if the saaiicataan can allow the block to be moved 
before it is locked. Applications should eo locking memory, and should unlock are memory 
blocks as-soon as possible. 


Purpose 

Syntax 

Description 

Uses 

Returns LPSTR, the new segment location. NULL on error. 
See Also GlobalUnWire(), GlobalLock(), GlobalFix) 
Parameters 

hMem 

Example 


HANDLE: The handle of the global memory block to unwire. This is the value fetumed edby Global- 
‘Alloc() or GlobalReAlloc() the last time the block was caval or resized. 


See He example above under GlobalUnWire(). 


LueEusPAces_ : | | mwind0 Wingo m Win 3.1 
Pavpase Limits the amount of rexpanded memory that Windows will assign to an application. 

Syntax void LimitEmsPages(DWORD dwKbytes); 

Description ‘This function has no effect unless expanded memory is installed and is being used under Win- 


‘dows. It will not affect — that bypass Windows’ memory manager by directly calling 
INT 67H. 
\ 


: 7 ~ 
- Returns : No returned value (void).: | 
dwKbytes DWORD: The number of kilobytes of expanded memory the aplication calling this function 
should be able to access. . . 
Long FAR PASCAL WndProc CHWND hwnd, unsigned inessags? worD apakda: LONG lParam) , 
ree Cilessage) 7 ; a fol process windows messages */ 
case WH_COMMAND: _t* process menu items */ 
oe (wParam) - a 
case IDM_DOIT: /* User’ hit the “Do it" menu item */ 
RA LimitEmsPages | (10) ; 
; ; break ; , 
[Other program lines] 
LoapMobute Bg fo se mWin2.0 mWin30 wWin3l 
Purpose _ Loads and executes a Windows program, or creates anew instance of the program if one ormore 
: ‘instances are already running. . . 
Syntax HANDLE LoadModale(LPSTR es li LPVOID lParometrBct) 


Description 
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>: 


| This function allows one Windows aulenin to load and run others. The function can pass the | 


loaded file a command line, like a file name to load on startup. 


Useful for creating master applications that run a series of “slave” programs. Also handy for load- 
ing the standard Windows applications like NOTEPAD.. 


’ HANDLE, the instance of the loaded module. LoadModuleQ) returns after the application loaded 
enters its message loop. If the value returned is less than 32, the module was not loaded. The 
possible error values are listed i in Table 14-6. 


2 aon asta CER Wet 
Q - Out of memory. 
2 File not found. 
3° Path not found. 
5 . Attempt to dynamically link to a task. 
6 Library requires separate data segments for each task. 
10 Incorrect Windows version. 
11 Non-Windows .EXE file. 
12 OS/2 application. 
“13 DOS 4.0 application. ' 
14 Unknown .EXE type. 
15 © Attempt to load a .EXE file created for an ane version of Windows. Only affects standard and 386 
enhanced modes. 
(6 Attempt to load a second .EXE containing multiple, writeable data segments, 
17 Attempt to load a second instance linked to.a nonshareable DLL. 
18 . Attempt to load a protected mode-only application in real mode. 
. Table 14-6 LoadModule() Error Codes. 
See Also WinExec() accomplishes the same purpose, but is somewhat simpler to use. 
kaModuleName _ LPSTR: A pointer toa null-terminated string containing the name of the applicationtorun.Ifno _ 
me Soe _extension is included, .EXE is assumed. If IpModuleName does not contain a directory path, 
7 Wiridows will search for the file based on the following search order: 
1. In the current directory. 
2. In the Windows directory. This is the directory containing WIN. COM. Use GetWindowsDirec- 
tory() to determine the path name of this directory. 
3. In the Windows system directory. Use the epee) function to determine the 
f path name of this directory. 
‘ 4, In the directories specified in the PATH environment variable. ‘This is the PATH command 
" that is executed from DOS, before Windows is loaded. Typical systems set their PATH values 
in the AUTOEXEC.BAT file. 
acne 5. Inthe directories mapped in a network. 
lgParemeterBlock LPVOID: This is a data structure containing four fields. For some reason, WINDOWS. H does not 


include this structure. Define the PARAMBLOCK data type as follows: 


651 


WINDOWS API BIBLE 


typedef struct tagParamBlock 
{ . 


WORD 
LPSTR 
‘ LPVOID 
DWORD 
} PARAMBLOCK ; 


| wEnvSeg 
| IpOmdLine 


lpCmdShow 


wEnvSeg ; /* usually NULL */ 
LpCmdLine ; /* command Line string */ 
LpCmdShow ; /* WORD wl2] */ 
dwReserved ; /* always NULL */ 


.The meaning of each of the fields is as follows. — 


WORD: The segment address of the environment under valitch the module is to run. This is the 
location of the environment variables like PATH. Set to NULL to use the Windows environment 
(normal case). 


LPSTR: A pointer to a null-terminated character string cbutatbing the command line. This is 
typically the file name that the application will run. The first character should be a blank space. 
Set to a null string (“”)if no command line is to be passed. 


LPVOID: This must point to an array of two WORD values. Set the first one equal to the number 
two. Set the second equal to one of the ShowWindow() style values in Table 14-7. 


Hides the doe The top window on Windows’ list is activated. 


- SW_HIDE 
SW_MINIMIZE Minimizes the window. The top window on Windows’ list is activated. 
SW_RESTORE Activates and displays the window (same as SW_SHOWNORMAL). 
SW_SHOW Activates and displays the window in its current size and position. 
SW_SHOWMAXIMIZED _ Activates and maximizes the window. | 
SW_SHOWMINIMIZED Activates and minimizes the window. 


SW_SHOWMINNOACTIVE Displays and minimizes the window. The currently active window remains active. 


SW_SHOWNA Displays the window, but does not change which window is active. 
SW_SHOWNOACTIVE Displays the window, but does not change which window is active. 
SW_SHOWNORMAL Activates and displays the window. If the window was minimized or maximized, ie window i is” 


retumed to its previous size and position. 


_ Table 14-7. lpCmdShow ShowWindow() Styles. 


dwReserved . 
; Example 


DWORD: A reserved value. Set equal to NULL. 


This program, illustrated in Figure 
14-19, creates a window that auto- 
matically loads the NOTEPAD.EXE 


ae generic : aus 
Dolt! Quit 

application and loads READ- 

ME. TXT into NOTEPAD (if the files File CiWINDOWSI\NOTEPAD.EXE, Reference Count 1 


exist). The program loads NOTE- Figure 14-19. LoadModule() Example. 

PAD.EXE while processing its own 

WM_CREATE message, so NOTEPAD appears before the GENERIC application. GENERIC dis- 
plays the full file name and reference count of the module it loaded (NOTEPAD). When the user 
clicks the “Do It!” menu item, the NOTEPAD application is sent a WM_DESTROY message, re- 
moving the program from memory. 


typedef struct tagParamBlock 
.¢ : 


WORD 
LPSTR 
LPVOID 
DWORD 


wEnvSeg ; 

LpCmdLine ; 
UpCmdShow ; 
dwReserved ; 
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+ PARAMBLOCK ; 


Long FAR PASCAL WndProc (¢ 
{ 
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HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


PAINTSTRUCT ps ; 

PARAMBLOCK pb ; 

char ° cWindName £128] ; 

char cBuf (2561, cCommandLine C] = " readme.txt" ; 
WORD wCmdShow C2] ; 

HANDLE hModule ; 

int nCount ; 

HWND hNotePad ; 

switch (iMessage) /* process windows messages */ - 


case WM_ CREATE: 


pb. wEnvSeg-=-0°; ao 

pb. lpCmdLine = (uPstR) cCommandLine ; 
wCmdShow C0] = 

wCmdShow £1] = Sd GRGUNGRBAL ; 
pb.lpCmdShow = weno stow ry 
pb.dwReserved = NULL ; 

LoadModule (“notepad. ‘exe’, (LPVOID) &pb) ; 
break ; 


case WM_PAINT: 


BeginPaint (hWnd, &ps) ; 
hModule = GetModuleHandle ("notepad") ; 
GetModuleFileName (hModule, cWindName, 127) ; 
nCount = GetModuleUsage (hModule) ; 
TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
“File 4s, Reference Count: %d", 
CLPSTR) cWindName, nCount)) ; 
endhaant ChWnd, &ps) ; ; . 
break ; 


case WH_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the “Do it™ menu item */ 
hNotePad = FindWindow (NULL, “Notepad - README.TXT") ; 
if (hNotePad) 
SendMessage ChNotePad, WM_DESTROY, 0, OL) ; 


b k >; 
case IDM_! quit: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; ; 
default: /* default windows message processing */ 
, return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
} 
return (OL) ; 
} 
LocaLALLoc oo mWin2.0 mWin3.0 mWin3t 
Purpose Allocates a block of memory in the local heap. 1 ay 
Syntax HANDLE LocalAlloc(WORD wFlags, WORD wBytes); . . 
~ Description This is the first step in allocating and using memory in the local heap. The maximum amount of 
3 ; memory in the local heap i is 64K, less the stack and static variable storage sizes. 
Uses : Local memory is idea! for small memory items. Access to local memory is faster than to global 
memory, as only a 16-bit address is needed. 
Returns _ HANDLE, the handle to the memory block allocated. Returns NULL on error. 


| 


‘WINDOWS AP! BIBLE 


See Also . Locallock(), LocalReAlloc(), Localfree() 


Parameters 
wFlags WORD: One or more of the flags in Table 14-8, ebinel with the U language binary OR spetiae 
(1). Choose either LMEM_FIXED or LMEM _MOVEABLE, and then combine the choice with other - 
options. 
_LMEM_DISCARDABLE «Ce ean memory Whee can ae discarded i Windows needs to pon room. Used only with 
- LMEM_MOVEABLE. 
LMEM_FIXED Allocates fixed memory. Do not use this unless absolutely necessary. Fi xed memory fi limits 
Windows’ ability to optimize memory use. .. 
LMEM_MOVEABLE Allocates moveable memory. 
LMEM_NOCOMPACT Memory in the local heap is not aaa or discarded to make room for the new memory 
vs block. , 
. LMEM_NODISCARD Memory in the local heap is not discarded to’ make room for the new memory block. 
LMEM_ZEROINIT initialize the new allocated memory block contents to zero: 


Table 14-8. LocatAlloc( ') Flags. — 
Whenever possible, use LMEM MOVEABLE. WINDOWS.H includes two common combinations: 


define LHND | c (LMEM_MOVEABLE | LHEM_ZEROINIT) eer ee eo 
#define LPTR GLMEM_FIXED | LMEM_ ZEROINIT) wee 

wBytes WORD: The number of ites 'to allocate. The actual number of bytes allocated may be slightly 
? higher, to ensure that the boundary ends on an even-numbered address. 

Example This example shows the allocation 


_ ofmemoryonthelocalheaptostore Fm iia Swit : 
a string. When the program first Ps: OI Fg es 


The memory biock ts 54 bytes in size——~- 
starts (WM_CREATE received), Contains: ABCDEF GHIJKLMNOPQRSTUVWXYZabcdef ghiximnoparstuvaag 


Flags: Discardable: 0. Lock Count 1 + ° 


- ‘ room for 27 characters is allocated. 
- A string is stored in the memory prghte 14-20. LocalAlloc() Evample. 

~ block. This string, along with the : 
block size and several memory status bytes, i¢displayed onthe window’ s client area every tia a ; 
WM_PAINT message is received. When the user clicks the “Do It!” menu item, the memory Whock 
is reallocated to make room for another 27 characters. The additional characters are written to 
the buffer and are displayed when WM_PAINT messages are processed. Repeatedly clicking the 
“Do It!” menu item does not allocate more room in this case. The block is simply reallocated to 
the same size, resulting in no change. Figure 14-20 shows the window's appearance after the ‘Do 
It!” menu item was clicked. | 


ov FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


PAINTSTRUCT . ps; ; . is aoa 
static HANDLE hMem; , bs 
cher *pMem, cBuf [128] ; 

int, ’ i, nSize, nFlags ; 

ee eS i nenege? /* process windows messages */ 


. case WM_CREATE: 
: _4f ChMem = LocaLAaltoc CLMEM. LAOVEABLE, 27)) 
t- 
if pees = Local Lock. ChMem)) 
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for (i =0 7 1< 26 ; i++) 
‘ *pNemt+ = "At +4 ; 
*pMem: =0O; 
LocalUnlock ChMem) = | a = 


else 
MessageBox Chwnd, 
“Could not lock memory block.", . 
“Memory Error", MB_ICONHAND | MB_OK) ; 


} 
else 
{ 
MessageBox (hWnd, "Could not allocate memory”, 
“Memory Error”, MB_ st CONHANP { MB_OK) ; 
DestroyWindow ChWnd) ; 
} 
break ; 


case WH_PAINT: . 
BeginPaint (hWnd, &ps) ; 
if (pMem = LocalLock ChMem)) 
{ 


nSize = LocalSize (hMem) ; 

nFlags = LocalFlags (hMem) ; 

TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
“The memory block is %d bytes in size.", 
nSize)) ; 

TextOut (ps.hdc, 10, 30, cBuf, wsprintf (cBuf, 
“Contains: %s", CLPSTR) pMem)) ; 

TextOut (ps.hdc, 10, 50, cBuf, wsprintf (cBuf, 
“Flags: Discardable: 4d, Lock Count: 4d", 
nFlags & LMEM L.DISCARDABLE, 
nFlags & EMER. LOCKCOUNT)) ; 

_LocalUnlock ChMem) ; 


} 
EndPaint ChwWnd, &ps) ; = 
break ; 
case WM_COMMAND: ~ . /* process menu items */ 
switch kwearam) 
{ a : ~ *. 
' case‘IDM_DOIT: I+ User hit the "Do it" menu item */ 
if ChMem = LocalReAltoc (hMem, (26 * 2) +1, 
mites MOVEABLE) ) 
€ 
a if (pMem = LocalLock ChMem)) 
{ 


for (4 =0; 1 < 26; 144) 
; . *phens+ ile skip over old stutf ef 
ae for (i =0°; i < 26; 4{++) 
we = . nk a = Va! + q ; 
Pere he 
| \u \ _  *pMem = 0; ; 


LocalUnlock ChMem) 7 


MessageBox (hWnd, 
"Could not lock memory block.", 
“Memory Error", MB_ICONHAND | MB OK) ; 


else’ é i - ea = 8 

= MessageBox (hWnd, “Could not re-allocate memory", 
"Memory Error", MB_ICONHAND | MB_OK) ; 
“Invatidaterect Chund, NULL, TRUE) p/* force paint xf. 
break ; 

case IDM_QUIT: oe send end of application message a] 

_LocalFree (hMem) ; 

DestroyWindow Chuind) ; 
break ; 

} 

: break ; be - , thé ee 

case WM_DESTROY: , -/* stop application */ 


‘WINDOWS API BIBLE. - 


PostQuitMessage (0) ; 
break ; 

default: ‘ /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return COL) ; 


} 

Loca Compact | mWin2.0 mWin30 mWin3.1 

Purpose Determines the amount of available memory in the local heap, compacting memory if necessary 

3 to increase space. 
Syntax WORD LocalCompact(WORD wMinFree), 
Description First, LocalCompact() checks to see if there arewMinFree bytes available in one contiguous area 
of the local heap. If not, LocalCompact() moves all unlocked, moveable blocks to the high memory 
end of the heap. If this still is not enough room, enough discardable blocks are removed from 
memory to make room for the requested size, or blocks are removed until there are no more 
discardable blocks to remove. . 

Uses Used to make room in the heap. If an application is creating and discarding memory in the heap 
constantly, the heap may become fragmented, which limits the size of blocks that can be allo- - 
cated. LocalCompact() reshuffles the memory blocks to make room available for the next. 

. LocalAlloc() or LocalReAlloc() function call. 

Returns WORD, the number of bytes in the largest available block of free memory in the local heap. 

See Also LocalAlloc(), LocalReAlloc(), LocalLock(), LocalUnlock(), LocalFree() 

Parameters a — A 

wMinkree WORD: The number of bytes desired. If wMinFree is zero, the function returns the amount of 


memory in the largest contiguous free block of memory, without compacting. 


Related Messages WM_COMPACTING 


Example 


ve 


ae 


This example, whichis illustratedin Before “Do tt!" pacer Dat, 

Figure 14-21, allocates four blocks [aRRIRMrnrrraa Meh caphieri ot [RTE 
of memory, each 64 bytes in length. 

Block 0 is moveable, block 1 is Block 0's address is ; Block 0's address is 6514. 
moveable and discardable, block 2 ‘I Block 1's address Is : Block I's addressis 0. 

: : Block 2's address Is ; Block 2's address is 6442. 
is moveable, and block 3 is fixed. } pBiock 3's address is 6032. | | Block 3's address is 6032. 


Each block’s address is displayed 
(after locking the blocks) whenthe Figure 4-21. LocalCompact() and LocalDiscard{) 
application processesa WM_PAINT Example. 

message. When the user clicks the 

“Do It!” menu item, block 1 is discarded. The heap is forced to be cGmpanted by requesting a 
block of memory larger than the largest available block. After compacting, block 2 is moved into 
discarded block 1’s place. Block 3 remains at the same location because it was given the 
LMEM_FIXED attribute. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ , = ae 


PAINTSTRUCT | te Se ps ; 
static: HANDLE hMem C4] ; 
- char - ; *pMem Ca), cBuf C128) ; 


int 


switch (iMessage) | a /* process windows messages */ 
OA ; le 


.i, nFree ; 
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case WM_CREATE: 


hMem CO] = LocalALloc (LMEM_MOVEABLE, 64) ; 
hMem C1] = LocalAlloc (LMEM_MOVEABLE | LMEM_DISCARDABLE, 64) ; 
hMem C2] = LocalAlloc (LMEM_MOVEABLE, 64) ; 

hMem £33 = LocalAltoc (LMEM_FIXED, 64) ; 


break ; 
case WM_PAINT: 
_ BeginPaint ChWnd, &ps) ; 
for (i =0; 1<4; i+t) 
{ 
pMem Cild = LocalLock (hMem €1]) ; 
TextOut (ps.hdc, 10, 20 * i, cBuf, wsprintf (cBuf, 
"Block %d's address is %6d.", i, pMem Lil)) ; 
LocalUnlock (hMem Cid) ; 
} : 
EndPaint (hWnd, &ps) ; 
break ; 
case WM_COMMAND: : /* process menu items */ 
switch (wParam) : 
{ 


case IDM_DOIT: ; /* User hit the "Do it" menu item */ 
LocalDiscard (hMem (€1]) ; 
nFree = LocalCompact (0) ; /* find free space */ 
LocalCompact (nFree + 16) ; /* force compact */ 
InvalidateRect (hWnd, NULL, TRUE) ; /* force paint */ 
break ; 

case IDM_QUIT: es send end of application message */ 


for (i =O; 1< 4; 71 ++) 
Localfree. Chem Cil> ; 
Postdui tMessage (NULL) 7. tpe ; \ 


break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 2 
} 
return (COL) ; 

} 

LocaLDiscarp , Win2.0 @Win3.0 mWin3.l 

Purpose Discards a memory block from the local heap. 

Syntax HANDLE LocalDiscard(HANDLE hMem). 

Description Discarding a memory block makes the space available for sibpidis other blocks of memory. The ~ 
hMem handle remains usable after the block is discarded, although it does not point to active 
memory. hMem can be reused by using LocalReAlloc() to allocate another block of memory. Only 
blocks allocated with the LMEM _DISCARDABLE and LMEM_MOVEABLE flags set can be dis- 
carded. 

Uses Discarding memory to make room for other blocks. Note that LocalFree() removes the aoa = 
block and invalidates the memory handle. LocalDiscard() discards the enemory block, but the 
hMem handle remains valid. 

Returns HANDLE. Equal to hMem if the function was successful, NULL on error. 

See Also LocalFree(), LocalReAlloc() 

Parameters . 

hMem HANDLE: The handle to the discardable memory block, returned by LocalAlloc(). 

Example See the previous example under LocalCompact(). 
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Y 


LocaLFLaGs | 


Purpose aoe 
Syntax. 


; mWin2.0 wWin3d0 mWin3! 
Determines if a memory block in the local heap is locked, discarded, or potentially discardable. 
WORD LocalFlags(HANDLE hMem); 


This function checks the status of a memory block allocated in the local heap. If a memory block 
is locked with LocalLock() more than once without calling LocalUnlock(), the block’s lock-count 
will be more than one. LocalUnlock() will have to be called as many times as the lock-count to 


unlock the memory area. Memory blocks can be discarded using LocalDiscard() and still have 


valid handles. LocalFlags() will determine if the memory block has been discarded, or if it was 
allocated using the LMEM_DISCARDABLE flag. 


-To check the validity of a memory handle, or to check if a memory block has been locked more 


than once. 
WORD. The high-order byte contains one of the flags in Table 14-9. 


LMEM_ DISCARDABLE 
LMEM_DISCARDED 


The block was allocated with the LMEM | DISCARDABLE fis 


The block has been discarded. The LocalReAlioc() function will need to be called to make the 
memory area usable, 


Table 14-9. LocalFlags( ’) Flags. 


| Example 


"The low-order byte contains the lock-count of the memory block. Combine the returned word 


with LMEM_LOCKCOUNT using the C language binary AND operator (&) to determine the lock- 
count. 


LocalAlloc(), LocalDiscard(), LocalReAlloc() 


HANDLE: The handle to the memory block allocated in the local heap with LocalAlloc(). 


~ See the example under LocalAlloc(). 


\ 


mWin2.0 wWin30 mWin31 


Frees a block of memory allocated in the local heap. 
HANDLE LocalFree(HANDLE hMem); 


Freeing a memory block returns the memory to the system for reuse. All memory blocks ‘aipeated 
within an application should be freed before the application exits, to return the memory to Win- . 
dows. 


. There should be a call to LocalFree() for every call to LocalAlloc() in a program. 


HANDLE, equal to hMem if the memory block was freed. NULL on error. 


: LocalAlloc(), LocalDiscard(), LocalReAlloc() 


HANDLE: The handle to the memory block allocated in the local heap with LocalAlloc(). 
See the example under LocalAlloc() for a complete example. The example below shows a short- 


cut way to allocate a small block of local memory for a quick purpose, and then immediately = 


delete it. The shortcut takes advantage of the fact that the block is allocated us’ .g the 
LMEM_FIXED attribute. The block does not have to be locked and unlocked. This techinque is 
only suitable for blocks that are used for a quick purpose and then discarded. 


/ 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 
PSTR pStr, pS2 ; 
int i; 


switch CiMessage) 


‘/* process windows messages */ 


"case WH_PAINT: 


pStr = (char NEAR *) LocalAlloc CLMEM_FIXED | LMEM_ZEROINIT, 
27) ; 
' pS2 = pStr ; 
i1=0; 1 < 26; i++) / 
*pS2+t = ro +i; 

BeginPaint (hWnd, &ps) ; 
TextOut (ps.hdc, 10, 10, pStr, 26) ; 
EndPaint (hWnd, &ps) ; 
LocalfFree (CLOCALHANDLE) pStr) ; 


break ; 
[Other program lines] 
LocALHANDLE OWin2.0 mWin30 8 Win3l 
Purpose Retrieves the handle of a memory block, given the address. 
Syntax HANDLE LocalHandle(WORD wMem); | Agi Lae 
Description This function returns the handle to a local memory block, given the address of the block. + 
Uses Used with fixed memory blocks to retrieve the handle so that the block can be freed using 
LocalFree(). . 
Returns HANDLE, the local memory block’s handle. 
* See Also LocalFree() 
Parameters 
wMem WORD: The address of the local memory block. 
Example This example illustrates a number of bad practices, so use the example as what NOT to do. The 


program allocates and locks a local memory buffer. The address is saved as the static variable 
pMem, and a text string is copied into the buffer. This string is displayed when a WM_PAINT 
message is received. Note that the memory buffer is not unlocked (it should be). When the user 
clicks the “Do It!” menu item, the local memory block is freed. This invalidates the memory block, 
but the static handle pMem remains unchanged. The WM_PAINT messages will start to output 
garbage, as the memory once used by the text block is used for other purposes by Windows. __ 


8 FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


PAINTSTRUCT “ps ; 

HANDLE hem ; 
static char *pMem ; 
char . cBuf £128] ; 


switch CiMessage) /* process windows messages */ 
case WM_CREATE: 
- hMem = LocalAlloc (LMEM LROVEABLE, 128) ; 
pMem = LocalLock (hMem) ; 
lstrepy (pMem, “This is bad example - fixed memory") ; 
break ; 
case WM PAINT: 
BeginPaint Chlnd, &ps) ; 
TextOut (ps.hdc, 10, 10, pMem, lstrlen (pHem)) ; 
EndPaint (hWnd, &ps) 5 
break ; 


\ 
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Vos ce 


LMEM_MODIFY 


LMEM_DISCARDABLE 


N 


case WM_COMMAND: /* process menu items. */ 
switch (wParam) , 


case IDM_DOIT: /* Free the memory block */ 
~ LocalFree (LocalHandle (CWORD) pMem)) ; 
- = break ; 
[Other program lines] 
LocaLLock Win2.0 mWin3.0 mWin3.1 
Purpose _ Locks an allocated memory block in the local heap. 
Syntax PSTR LocalLock(HANDLE hMem), | 
Description Memory blocks allocated with LocalAlloc() must be locked before data can be written to or read 
ae et from the memory area. The block should be unlocked with LocalUnlock() as soon after use as 
ss possible. 
Uses Used to “realize” a memory pointer. This means that the return value is a far pointer to a block of 
memory. . 
Returns PSTR, a near pointer to the beginning of the memory area. 
See Also LocalUnlock(), LocalAllocQ) 
Parameters ; 
hMem HANDLE: A handle to the memory area allocated with LocalAlloc(). 
Example See the example under LocalAlloc(). _ 
LocaLREALLOC Win2.0 mWin30 mWin3.1 
Purpose Changes the size and/or attributes of a local memory block. 
Syntax HANDLE LocalReAlloc(HANDLE hMem, WORD wBytes, WORD wFlags); 
Description Once a memory block is allocated with LocalAlloc(), it can be resized using LocalReAlloc() as 
needed to fit the program’s data needs. Discardable memory blocks use this function to restore 
‘ the memory block. 
Uses Usually used to increase the size of a data block as new items are added. It can also bé used to 
change the memory attributes from moveable to fixed, ete: 
Returns HANDLE, the handle of the resized memory block. Returns NULL on error. The returned value 
will equal hMem unless the LMEM_MOVEABLE flag is set. 
See Also LocalAlloc(), LocalDiscard() 
Parameters . 
hMem HANDLE: The handle of the memory block in the local heap, initially allocated with LocalAlloc(). 
wBytes WORD: The new size of the memory block. Local memory blocks are limited to the size of the 
local heap (64K, less the size of the stack and static variable storage space). 
wFlags WORD: The type of memory to reallocate. This should be one or more of the flags listed in Table 


14-10, combined with the C language binary OR operator (1). Choose either LMEM_FIXED or 
LMEM_MOVEABLE, and then combine the choice with other options. 


Specifies that the attributes’of the memory block will be changed. The wBytes parameter is 
ignored. Used only with LMEM_DISCARDABLE. 
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LMEM_MOVEABLE Moveable memory. If wBytes is zero, this flag causes a previously fixed block to be freed, or a 
previously moveable object to be discarded. This only occurs if the block has not been locked. 
If wBytes is nonzero and the hMem block is fixed, LocalReAlloc() will move the block to a new 
fixed location. This means that the returned value will not be the same as hMem. Cannot be 
used with LMEM_MODIFY. 


LMEM_NOCOMPACT Memory in the local heap is not compacted or discarded to make room for the resized memory 
block. Cannot be used with LMEM_MODIFY. 
LMEM_NODISCARD Memory in the local heap is not discarded to make room for the resized memory block. Cannot 
, be used with LMEM_MODIFY. 
LMEM_ZEROINIT initializes the new part of the allocated memory block to zero. Cannot be used with 
LMEM_MODIFY. 
Table 14-10. LocalReAlloc() Flags. . 
Caution If the program’s data segment is defined as moveable in the .DEF file, calling LocalAlloc() may - 
cause the data segment to move. This will invalidate automatic (stack) variable pointers. 
Example See the example under LocalAlloc(). 
LocaLSurink aWin2.0 mWin3.0 eBWin31 
Purpose ‘Reduces the size of the local heap. . 
Syntax WORD LocalShrink(HANDLE hSeg, WORD wSize); 
‘Description - The local heap is increased in size as needed to hold new objects allocated with LocalAlloc() and 


LocalReAlloc(). The heap is not automatically reduced in size, even if objects are freed or dis- 
carded. LocalShrink() reduces the heap in size. The minimum size is defined in the application's 
.DEF definition file as the HEAPSIZE statement. 


Uses Making global: memory room available, by reducing the size of an application’s local heap. Call in 


: response to a WM_COMPACTING message. LocalShrink() does not affect the size of the stack. 
Returns WORD, the size of the local heap after shrinkage. : 
See Also LockData(), UnlockData() : 
Parameters _ a . 
hSeg HANDLE: The handle of the local data heap. This value can be obtained by calling LockData(). 
wsize WORD: The desired size of the local heap after shrinkage. 
Example This example allocates four discardable memory blocks on the local heap. When the user clicks 


the “Do It!” menu item, two of the blocks are discarded, and the local heap is reduced in size. All 
of the discardable memory blocks end up discarded after the local heap is reduced in size. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . 


PAINTSTRUCT ps; 

static HANDLE hMem C4] ; 

HANDLE | hSegment ; 

char *pMem C4], cBuf C128] ; 

int i, nFree, nlHeap ; 

switch (iMessage) . /* process windows messages */ 
{ ! 


case WM_CREATE: 
for (§=0; 1<4; i++) 
hMem Ci] = LocalAlloc (LMEM_MOVEABLE | 
LMEM_DISCARDABLE, 2048) ; 
break ; . 
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case WM_! PAINT: 
BeginPaint Chind, &ps) ; 
for (§=0;1<4;3 i++). 
{ 
pMem CiJ = LocatLock (hMem Lil) ; 
TextOut (ps.hdc, 10, 20 * i, cBuf, wsprintf (cBuf, 
“Block %d's address is %6d.", i, pMem Cil)) ; 
LocalUnlock (hMem Cid) ; 
} — 
EndPaint ChWnd, &ps) ; 
break ; ; : 
case WM_COMMAND: /* process menu items */ 
- switch (wParam) 


case IDM_DOIT: /* User hit the ae it" menu item */ 
LocalDiscard (hMem (11) ; 
LocalDiscard (hMem (3]) ; 


nFree = LocalCompact 163 4 /* find free space */ 
LocalCompact (nFree + 16) ; /* force compact */ ‘ 
' hSegment = LockData (0) ; /* get segment */ 


UnlockData (0) ; 
nLHeap = LocalShrink (hSegment, 6144) ; 
InvalidateRect (hWnd, NULL, TRUE) ; 
break ; = 
case IDM_QUIT: “/* sand end of application message */ 
for (i=0;31<4; i ++) 
LocalFree shier Cid) ; 
Dee thayelnuce pnd 


break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitHessage (CO) ; 
break ; 
default: /* default windows message processing-*/ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


3 
~- peturn COL) ; 


} 

LocaLSIzE eWin2.0 mWin3.0 Wind! © 

Purpose Determines the size of a memory block allocated in the local heap. 

Syntax — WORD LocalSize(HANDLE hMem); 

Description This function determines the actual number of bytes allocated in the local heap by LocalAlloc() 
and/or LocalReAlloc(). The number of bytes may be slightly larger than the number requested, as 

the allocated block will be sized to end on an even memory address. 

Returns WORD, the actual size of the memory block in bytes. NULL ifhMem is not a valid memory handle. 

See Also LocalFlags(), LocalAlloc() 

Parameters 

hMem HANDLE: The handle of the local memory block. 

Example See the example under LocalAlloc(). | 

LocaLUNLocK. . | Win20 @Win3.0 mWin3.1 

Purpose Unlocks a locked memory block in the local heap. ; 

Syntax BOOL LocalUnlock(HANDLE hMem), 

Description ’ Unlocks a memory block. Once unlocked, the memory block can be moved by Windows, unless the 


block was allocated with the LMEM_FIXED flag. Unlocked blocks can also be discarded, if they 


. were allocated with the LMEM_DISCARDABLE style. If a memory block is locked more than 
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once without unlocking, the block's reference count will be more than one. LocalUnlock() will 
have to be called the number of times specified by the reference count before the block can be . 


_ moved or discarded. 
Uses Memory blocks should be unlocked as soon after being locked as possible. This makes it possible 
- for Windows to make maximum use of the memory space. 

Returns BOOL. Zero if the block's lock-count is zero (completely unlocked), nonzero if not. 

See Also LocalLock(), LocalAlloc() 

Parameters , 

hMem HANDLE: The handle of the local: memory block to unlock. This is the value initially returned by 

. LocalAlloc(). 

Example . See the example under LocalAlloc(). 

Purpose _ Locks a segment in memory. 

Syntax HANDLE LockSegment(WORD wSegment); 

Description Locking a segment in memory is normally not desirable, as it limits Windows’ ability to make 
maximum use of memory. Some programming elements, such as interrupt handlers, require a 
locked program segment to be efficient. The size of the segment that must be locked should be 
kept as small as possible and should be unlocked whenever possible. 

Uses Generally used to lock specific program segments. Can also be used to lock the program’s data 
segment, as shown in the example. ~ 

Returns HANDLE, the locked segment’s handle, or NULL on error. 

See Also UnlockSegment(), LocalinitQ) 

Parameters 

wSegment WORD: The segment address of the segment to be locked. If wSegment equals —1, the 
-application’s data segment is locked. 


Example. This example locks the entire data segment while the program is running. As a consequence, the 
pointer to a memory block allocated within the segment remains valid, even though the block was 
allocated with the LMEM_MOVEABLE attribute. This is not a good programming practice under 

normal conditions. . 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


- PAINTSTRUCT ps ; 
static HANDLE hMenm ; 
static char *pMem ; 
char cBuf £128] ; 
“switch CiMessage) /* process windows messages */ 


case WM_CREATE: 
LockSegment (-1) ; 
hMem = LocalAlloc *CLMEN OVERSEE? 128) ; 
pMem = LocalLock (hMem) ; 
strcpy (pMem, 
“Block moveable, but segment in fixed memory") ; 
LocalUnlock ChMem) ; 
break ; 
case WM_PAINT: 
.BeginPaint Chwnd, &ps>) ; /* note no locking of hMem */ 
TextOut (ps.hdc, 10, 10, pMem, Lstrlen (pMem)) ; 
EndPaint (hWnd, &ps) ; 
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} 


break ; . 
case WM_COMMAND: /* process menu items */ 

switch (wParam) 

{ 


case IDM_DOIT: /* User hit the “Do it” menu item */ 
break ; 
case IDM_QUIT: /* send end of application message */ 


LocalFree (hMem) ; 
UnlockSegment (-1) ; 
Pest roymindow ChWnd) ; 


break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; / 
break ; 
default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


} 
MutDiv 
Purpose 
Syntax 
Description 


Uses 
Returns 


Parameters 
nNumber 


nNumerator 
nDenominator 
Caution 


Example | 


BWin2.0 wWind0 wm Wind. 
Computes the result of (a * b) / c, where a, b, and c are short integers. 
int MulDiv(int xMumber, intnNumerator, int nDenominator); 


Short integers are limited to 16 bits of precision. This limitation frequently results in truncation 
problems when doing address arithmetic or graphics calcula- 
tions. MulDiv() deals internally with the values as 32-bit num- 
bers, reducing truncation errors. 


PDoltl quit | 


Address arithmetic and graphics calculations. 


; . Answer done wr = -29 
int, the result of (2Number * nNumerator) /nDenominator. > ses 


Answer done right = 6000 


int: The value a in the formula (a*b)/c. | Figure 14-22. MulDiv( ) 
int: The value b in the formula (a * b) /c. Ex sit sa 
int: The value c in the formula (a * b) /c. 


The result is not guaranteed to be correct! For example the calculation 20000 * 30000 / 10000 will 
overflow because the multiplication exceeds the 32-bit precision used. 


This example shows the calculation (2000 * 3000) / 1000. Done with pure integer math, the values 
overflow the 16-bit limit of short integer math. Using MulDiv() provides the correct result. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HDC hDC ; 
int ni, n2, n3, nAnswer ; 
char cBuf £128] ; 
switch (iMessage) /* process windows messages */ 
{ 
. case WM_COMMAND: /* process menu items */ 
switch (wParam) ; 
{ 5 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
ni = 2000 ; 
n2 = 3000 ; 
n3 = 1000 ; 
«nAnswer = (n1 * n2) is n3; /* wrong! */ 


hDC = GetDC (hWnd) ; 
TextOut ChDC, 10, 10, cBuf, wsprintf Gout, 
"Answer done wrong = 4d", nAnswer))' 2 
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nAnswer = MulDiv (n1, n2, n3) ; /* correct */ 
TextOut (hDC, 10, 30, cBuf, wsprintf (cBuf, 

“Answer done right = %d", nAnswer)) ; 
ReleaseDC (hWnd, hDC) ; 


break ; 

[Other program lines] 

UNLOCKSEGMENT oOWin2.0 gWin30 oWin31 

Purpose Unlocks a memory segment locked with LockSegment(). 

Syntax BOOL UnlockSegment(WORD wSegment); 

Uses Locked segments are used for special purposes, such as for interrupt handlers. Any segment 
locked in memory by LockSegment() should be unlocked before the application terminates. 

Returns BOOL. Zero if the segment is completely unlocked, nonzero if the segment lock-count is not zero. 
UnlockSegment() may have to be called more than once to unlock the segment if LockSegment() 
has been called more than once. 

See Also LockSegment() 

Parameters 

wSegment WORD: The segment address of the segment to be unlocked. IfwSegment equals —1, the segment 
is the program’s data segment. 

Example See the example under LockSegment(). 

WINEXXEC Win2.0 oWin3.0 oWin3t 

Purpose Loads and executes a Windows or DOS program, or creates a new instance of the program if one 

“or more instances are already running. 

Syntax WORD WinExec(LPSTR lpCmdLine, WORD nCmdShow); 

Description This function allows one Windows application to load and run others. The function can pass the 
loaded file a command line, such as a file name to load on startup. Unlike LoadModule(), Win- 
Exec() will execute a DOS application. 

Uses Useful for creating master applications that run a series of “slave” programs, Also handy for load- 
ing the standard Windows applications such as NOTEPAD. NOTEPAD can provide instant editing 
facilities for applications that need to process simple text files. 

Returns 


WORD. If the value returned is greater than 82, the function was successiul. Otherwise, one of the 
error codes in Table 14-11 will be returned: 


Out of memory. 


File not found. 

Path not found. 

Attempt to dynamically link to a task. 

Library requires separate data segments for each task. 
Incorrect Windows version. 

Non-Windows .EXE file. 

OS/2 application. 

DOS 4.0 application. : 
Unknown .EXE type. 


665 


WINDOWS API BIBLE 


Table 14-11. continued , 


16 Attempt to load an .EXE file created for an earlier version of windows: Only affects standard and 


386 enhanced mcdes. 
16 Attempt to load a second .EXE containing multiple, writeable data segrnents. 
17 Attempt to load a second instance linked to a nonshareable DLL. 
18 Attempt to load a protected mode-only application in real mode. 


Table 14-11. WinExec() Error Codes. 


See Also LoadModule() will accomplish the same purpose. 
Parameters Pe | 
lpCmdLine LPSTR: A pointer to a null-terminated string containing the name of the application to run. If no 


extension is included, .EXE is assumed. If lpCmdLine does not contain a directory path, Windows 
will search for the file based on the following search order: 


1. Inthe current directory. 


2. -In the Windows directory. This is the directory containing WIN.COM. Use GetWindowsDirec- 
tory() to determine the path name of this directory. ~ 

3. Inthe Windows system directory. Use the GetSystemDirectory() function to determine ne 
path name of this directory. 


4. Inthe directories specified in the PATH environment variable. This is the PATH ‘command 
that is executed from DOS before Windows is loaded. Typical systems set their PATH values 


in the AUTOEXEC.BAT file. 
5. In the directories mapped in a network. 
nCmdShow WORD: Set equal to one of the values in Table 14-12 for a Windows application. For a DOS appl 


cation, the .PIF file (if any) will determine how the application j isrun. 


SW_HIDE Hides the window. The top window on Windows’ list is.activated. - 


* SW_MINIMIZE Minimizes the window. The top window on Windows’ list is activated. 
SW_RESTORE Activates and displays the window (same as SW_SHOWNORWMAL). 
SW_SHOW Activates and displays the window in its current size and position. 
SW_SHOWMAXIMIZED Activates and maximizes the window. , 
SW_SHOWMINIMIZED Activates and minimizes the window. 
~ SW_SHOWMINNOACTIVE — - Displays and minimizes the window. The currently active window remains active. 
SW_SHOWNA Displays the window, but does not change which window is active. 
SW_SHOWNOACTIVE Displays the window, but does not change which window is active. 
SW_SHOWNORMAL Activates and displays the window. If the window was minimized or maximized, the w findow | is 


returned to its previous size and position. 


Table 14-12. lpCmdLine ShowWindow() Styles. 


Related Messages Send a WM_DESTROY message to a running application to remove it from the system. 
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Example _ This example runs the NOTEPAD.EXE application and has it load the README. TXT file when the 
user clicks the “Do It!” menu item. NOTEPAD is closed (sent a WM_DESTROY message) when 
the example application’s “Quit” menu item is clicked. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
“HANDLE hNotePad ; 
stitch (iMessage) /* process windows messages */ 
case WM_COMMAND: _ /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
WinExec (‘notepad.exe readme.txt", 
SW._SHOWNORMAL) ; 
break ; : 
‘case IDM_QUIT: /* send end of application message */ 
hNotePad = FindWindow (NULL, “Notepad —- README.TXT") ; 
if ChNotePad) 
SendMessage (hNotePad, WM_DESTROY, 0, OL) ; 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
‘default: /* default windows message processing */ 


_teturn DefWindowProc (hind, iMessage, wParam, lParam) ; 


} : 
return COL) ; 
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Bitmaps are blocks of pixel data that can be output directly to a device, such as a video display. You can think of them 
as a way to store the pixel data directly from the screen into a memory buffer. Painting bitmaps onto the screen is fast, 
much faster than using GDI functions like Rectangle() and LineTo(). The drawback to bitmaps is that they take up a . 
lot of memory and/or disk space. Literally, every pixel has to be saved. Prior to the 3.0 version of Windows, there was 
only one bitmap format, the device-dependent bitmap (DDB), or “old” bitmap format. Windows 3.0 introduced a 
second kind of bitmap called a “Device-Independent Bitmap” (DIB). Both formats have their purposes. 


DDB Bitmap Format 


The simplest bitmap form is the one for a black and white Gonpenbone) image. In this case, we can use one bit to 
store each piel s color, 0 for black and 1 for white. A ae outlined rectangle would be stored as 


0000000000000000 0x00 


0411111111111110 Ox7E 
OTETTTIIA T1410 Ox7E - 
0000000000000000 0x00 


This example would encode the 64 black and white pixels with eight bytes of data. If the bitmap is copying a color 
display, then more than one bit will be required for each pixel. For example, a 16-color VGA display would require four - 
bits to encode the color of each pixel. The same rectangle would require 4 * 64 = 256 bits, or 32 bytes of data to encode 
the pixels. Typically, bitmaps are not copies of an entire screen or page. Usually, they are small images, such as custom 
button faces. In order to make sense out of the pixel data, Windows starts the DDB bitmap data with some header 
information. The BITMAP data type is defined in WINDOWS.H as follows: 


© Bitmap Structure 
typedef struct tagBITMAP 
{ 


int bmType; /* always zero */ 
int bmWidth; /* width in pixels */ 
int bmHeight; /* height in pixels */ 
int bmWidthBytes; /* bytes per Line of data */ 
' /* must be a multiple of 2 */ 
- BYTE: bmPlanes; /* the number of color planes */ 
BYTE bmBitsPixel; /* the number of bits per pixel */ 
LPSTR bmBits; /* far pointer to the bitmap data */ 
+} BITMAP; : 
typedef BITMAP *PBITMAP; 
typedef BITMAP NEAR = *NPBITMAP; 
typedef BITMAP FAR *LPBITMAP; 


The BITMAP structure allows two different ways to specify the number of color bits used in the pixel data. 
bmPlanes is the number of color planes a device, such as a VGA display, may use. If this value is used, then. 
bmBitsPixel will be set to one. bmBitsPizel is the number of bits per pixel for a device that does not use color planes. 
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If this value is used, bmPlanes will be set to one. The function CreateCompatibleBitmap() will set these color values 
to match a physical device, so you do not have to know how colors are stored internally by the device. The actual pixel 
data is stored in a memory buffer pointed to by bmBits. This buffer is normally right after the header data in memory, 
although it can be located separately, as shown in Figure 15-1. 


Using DDB Bitmaps 

The most common way to use bitmaps in a pro- ca ati a 

gram is to display bitmaps created with the Figure l 15. 1 The DDB : Bitmap Format i in senior 

SDKPaint application. SDKPaint creates bit- 

maps that are stored as disk files. (SDKPaint actually creates DIB bitmaps, which are explained below. This format is 
converted automatically to the DDB format when LoadBitmap() is called.) Bitmap files created by SDKPaint can be 
added to a program’s .RC resource file with the BITMAP statement 


Fixel Data 


pen BITMAP pen.bmp 


This example loads a file called PEN.BMP and gives the bitmap resource the name “pen.” This example bitmap 
was created 60 pixels wide and 60 pixels tall. With the bitmap loaded as pare of the application’s resources, it is a 
simple matter to bring a bitmap into memory using LoadBitmap(). 

HBITMAP hBitmap ; 
hBitmap = LoadBitmap (hInstance , "pen") ; 

Pasting the bitmap image on the screen is a little more involved than you might expect. There is no futction 
called PaintBitmap(). Instead, the application loads the bitmap into a memory object called “Memory Device Con- 
text,” and then paints the memory device context onto the screen. Here is some example code. 


HDC hDC, hMemDC ; 
hDC = GetDC (hWnd) ; /* get screen DC */— 
hMemDC = CreateCompatibleDC ChDC) ; /* create memory DC */ 


SelectObject (hMemDC, hBitmap) ; 

BitBLt (hDC, 10, 10, 60, 60, hMemDC, 0, 0, SRCCOPY) ; 

DeleteDC (hMemDC) ; 2 

ReleaseDC ChWnd, hDC) ; 

The function that paints the bitmap onto the screen is BitBIt(). It copies bitmap data from one device context to 

a second device context. To make the bitmap data available through a device context, we first create a device context 
in memory that has the same attributes as the display. To do this, use CreateCompatibleDC(). Once we have the 
memory device context, the bitmap can be selected into it with SelectObject(). Finally, BitBltQ is called to do the 
actual painting. ‘ 


Memory Device Contexts 


The previous example probably seems a little involved, but there is a payoff. When a bitmap is selected into a memory 
device context, you can paint on the memory device context just like you paint on the screen or printer’s device 
context. All of the standard GDI functions, like LineTo() and Rectangle(), work just fine painting into the memory 
device context. As soon as the painting is done, the memory device context can be copied to the real screen with 
BitBlt(). 

Why not just paint directly on the screen? You can, but there are a few situations where it is much better to paint 
to the memory device context, and then copy the memory image to the screen or printer. One use is when repeating 
patterns. If you have to paint the same object over and over, just paint it once to memory and then copy it to the screen 
when you need it. BitBlt() and related functions are much faster than using the GDI functions, such as Rectangle(). 

. Another reason to paint on 4 memory device context is to avoid having the painting operations visible to the user. 
Although Windows 3.0 paints quickly, it is frequently possible to see different parts of the image being painted, one 
line or rectangle at a time. Avoid this situation by painting to a memory device context, and then using BitBlt() to copy 

to the screen. 
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Stretching and Painting Bitmap Images. 

In addition to BitBlt(), there are functions for pasting a bitmap onto a device context that allow the bitmap to be 

_ stretched or compressed. StretchBlt() does this for ‘the DDB bitmap type. If the bitmap is increased in size, extra bits 
matching the colors of their neighbors are added to fill in the missing bits. This technique is acceptable for modest 
enlargements, but will produce ragged edge onda lines if the expansion is too large. When a bitmap is reduced 
in size, some pixels have to be eliminated. In bitmaps with thin lines, the lines may be eliminated if they happen to fall 
on arow or column that is deleted. To save their information during compression, you can set the “stretching mode” 
of the device context using SetStretchBltMode(). Three modes are provided. One preserves white pixels, one pre- 

“serves black (colored) pixels, and one just deletes pixels. 

When painting a bitmap onto a device context, you would normally want to cover up any underlying image data. 

- There are other choices. Windows can do Boolean (binary) logic on both the source and destination pixels, and-have 
each pixel painted as a result of these calculations. For example, instead of painting the bitmap directly, the bitmap 
pixels can be compared to the destination pixels using an XOR operator. This technique has the advantage of allowing 
a bitmap to be erased by painting it twice in the same location. 

These Boolean comparisons are called “Raster-Operation Codes.” There are 256 possible combinations of the 

. source and destination data. They are defined in the Windows SDK documentation in Volume 2, Table 11.8. You © 
probably will never use more that two or three of these possibilities. The most common choices are given names in 
WINDOWS.H and are listed in Table 15-1, along with their Boolean logic equivalent. For the Boolean codes, “S” is the 
source bitmap, “D” is the destination bitmap, and “P” is the currently selected brush (called a “pattern”). The Boolean 
persion follow the C anguage’ conventions. 


BLACKNESS Tums all output black. (0) ; | 
DSTINVERT Inverts the destination bitmap. (~D) 
MERGECOPY The source and destination bitmaps are combined with the Boolean AND operator. (P & S) 
MERGEPAINT The source and destination bitmaps are combined with the Boolean OR operator. (~S | D) 
NOTSRCCOPY ~~ _sInverts the source bitmap, then copies it to the destination. (~S) 
NOTSRCERASE Inverts the result of combining the source and destination bitmaps using the Boolean OR operator. (~(S 
| D)) S| 

PATCOPY Copies the pattern to the destination. (P) 
PATINVERT _ Combines the destination ee with the pattern using the SetStretchBitMode OR operator. . A ‘D) 
PATPAINT P|~(S1D) 
SRCAND ’ Combines the source and destination bitmaps with the Boolean AND operator. (S & b) 
SRCCOPY . Copies the source to the destination. (S) 

2 SRCERASE $&~D 

: ‘SRCINVERT Combines the source and destination bitmaps using the Boolean XOR operator. (S “ D) 

- SRCPAINT Combines the source and destination bitmaps using the Boolean OR operator. (S | D) 
WHITENESS Tums all output white. This is a quick way to blank a device context. (1) 


Table 15-1. Raster-Operation Codes. - 


Problems with the Old.Bitmap Format 


The old bitmap format works well for copying parts of the screen into memory and pasting them back onto other 
locations on the screen. Windows provides extensive support for this type of operation, using memory device contexts. 
We will examine these later in this chapter. 
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Problems occur when your program needs to save bitmap data on disk files, and then display it on some other type 
of device. The old bitmap header does not have a place to store the colors used in creating the bitmap. There is an 
underlying assumption that the bitmap will be displayed on the same type of device, with the same arrangement of 
colors on color planes or in color bits. If you display an old bitmap on some other device, the colors may end up: 
completely different. This was not a big issue when EGA and VGA systems were the only devices available. Today, with 
Super VGA and other expanded color displays becoming widespread, Windows must provide a better way to store 
bitmaps so that they will be properly displayed on any device. 


Device-Independent Bitmaps (DIB) 
The device-independent bitmap, called a DIB, is the Windows 3.0 solution to the shortcomings of the old bitmap 
format. The big difference between DIBs and old bitmaps is that DIBs include a table of the colors the bitmap will use. 
The header format is also more complex. 

OnethingtokeepinmindisthattheDIBformat |. °°. oe oe SQUAD clr data" 
is not a graphics object like a DDB. You cannot se-  *=~—-+—-+++---—~ 
lect a DIB into a device context. Think of the DIB Figure. 15-2 Device-Independent Bitmap (DIB) Format. 
specification as a data format. It is a standard way 
of storing bitmap data along with the color data needed to reproduce the bitmap image. ‘The DIB format consists of 
three sections. The first one is the BITMAPINFOHEADER, shown in Figure 15-2. 


typedef struct tagBITMAPINFOHEADER{L 


DWORD biSize; /* size of BITMAPINFOHEADER */ 
DWORD biWidth; /* width in pixels */ 
DWORD biHeight; /* height in pixels */ 
WORD biPlanes; /* always 1 */ 
. WORD biBitCount; /* color bits per pixel */ 
; /* must be 1, 4, 8 or 24 */ 
DWORD biCompression; (* BI_RGB, BI_RLES8 */ 
/* or BI_RLE4 */ 
DWORD biSizelImage; ; /* total bytes in image */ 
_DWORD bixPelsPerMeter; /* 0, or opt. hres. */ 
DWORD biYPelsPerMeter; /* 0, or opt. v res. */ 
DWORD | biClrUsed; /*® normally 0, can set a */ 
/* lower no. colors than biBitCount */ 
DWORD biClrimportant; /* normally O */ 


> BITMAPINFOHEADER; 


typedef BITMAPINFOHEADER FAR *LPBITMAPINFOHEADER; 

typedef BITMAPINFOHEADER *PBITMAPINFOHEADER; 
Although similar to the BITMAP header structure, BITMAPINFOHEADER contains some added fields. The 

biBitCount element contains the number of color bits per pixel, either 1, 4, 8, or 24 bits. Table 15-2 describes these 

values. 


1 A monochrome bitmap. Each bit in the bitmap data will represent one pixel. 


Ae A bitmap with 16 colors. Each pixel requires four bits of information | in the bitmap data. The four bits 
: represent an index in the color table. 


8. A bitmap with 256 colors. Each pixel requires a byte of information in the bitmap data. The byte value 
represents an index into the color table. 


24 A bitmap with 224 colors. Each pixel requires three bytes of information, representing the RGB (Red, 
Green, Blue) color bytes. 


Table 15-2. Color Resolutions. 
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The biCompression element contains a value to define how.the vitmap. is-compressed (to save space) in the 
memory buffer holding the pixel data. If it is set to BI_RGB, no compression is used. BI_RLE4 is a four bits per pixel 
run length encoding compression. BI_RLES is arrcight bits per pixel compression. . 

~ biSizelmage is the bitmap size in bytes. Each row of pixels data must terminate on a 32-bit (DWORD) boundary. 
If a row of pixels, with the specified number of color bits per pixel, does not end at an even 32-bit number, the 
remainder is padded with zero bits. 

The last four values are not usually used. The biXPelsPerMeter and bi¥PelsPerMeter values can be used to encode 
the bitmap resolution in pixels per meter. Set both to zero if these elements are not needed. biClrUsed specifies the 
number of color values in the color table (described below) that are actually used. biCirUsed is normally set to zero, 
meaning that all colors are used. This value must be set to zero if the bitmap is compressed. biClrImportant specifies 
the number of critical colors. biClr/mportant is normally set to zero, meaning that all of the colors are important. ° 

After the BITMAPINFOHEADER structure, a DIB will contain the color table. This is a set of RGBQUAD data 
structures, holding the RGB color for each of the colors used in the bitmap. There will be as many RGBQUAD entries 
as there are color choices in the bitmap. For example, if biBitCount is four, there will be 16 color possibilities, requir- 
ing 16 RGBQUAD elements to define, taking up 16 * 4 = 64 bytes of space, assuming biCirUsed is set to zero. If 
biClrUsed is set to a value above zero, the biClrUsed value will be the number of RGBQUAD elements. 


typedef struct tagRGBQUAD { 


BYTE rgbBlue; /* blue intensity, O - 255 */ 
BYTE rgbGreen; /* green intensity, O - 255 */ 
BYTE rgbRed; : /* red intensity, 0 - 255 */ 
BYTE rgbReserved; /* reserved, set to zero */ 

+ RGBQUAD; 


Windows provides an alternative to specifying the bitmap colors using RGB color values. The color table can be an 
array of 16-bit unsigned integers, each of which is an index into the currently realized logical palette (see Chapter 12, 
Color Palette Control). Using pallet index values allows bitmap colors to change as the palette is changed. Several of 
the DIB functions include a wUsage parameter that can be set to DIB_PAL_ COLORS if the color table contains 
palette entries. DIB. PAL_COLORS informs Windows not to interpret the values as 32-bit RGB colors. You can use 
palette colors in a DIB in a memory device context. RGB colors should be used if the bitmap is to be saved to disk, 
potentially for use by some other type of device which may have a different color resolution. . 

WINDOWS.H includes two other structure definitions that are useful in manipwlabing: DIBs. The BITMAPINFO 
structure simply combines the first two parts of a DIB into one structure. 


typedef struct tagBITMAPINFO { 


BITMAPINFOHEADER bmiHeader;. 
RGBQUAD bmiColorsl(1]; 
} BITMAPINFO; 
typedef BITMAPINFO FAR *LPBITMAPINFO; 
typedef BITMAPINFO *PBITMAPINFO; 


Note that the RGBQUAD element bmiColors shows only oné element. This element is a placeholder, as the num- 
ber of colors will be greater than one, but it is not fixed for all DIBs. The application using a DIB will allocate : a 
memory block to hold the entire DIB structure, including all of the colors needed. 

The last structure is used only when DIBs are stored to disk. The BITMAPFILEHEADER structure is the first part ~ 
of a bitmap stored as a disk file. This is the way Windows PaintBrush and SDKPaint applications store their outputs. 


typedef struct tagBITMAPFILEHEADER { ‘ 
WORD bfType; /* always equal to 'BM' */ 


DWORD bfSize; /* size of file in DWORDs */ 

WORD bfReserved1; /* set to zero */ 

WORD bfReserved2; /* set to zero */ 

DWORD bfOffBits; /* byte offset from BITMAPFILEHEADER to Ad 


/* bitmap pixel data in the file */ 
} BITMAPFILEHEADER; 
typedef BITMAPFILEHEADER FAR *LPBITMAPFILEHEADER; 
typedef BITMAPFILEHEADER *PBITMAPFILEHEADER; | 


Figure 15-8 shows how the four elements of a complete DIB are arranged in a disk file. 
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Working with DIBs 


As mentioned, the SDKPaint applica- 

tion allows you to create bitmaps and = Figure 15-3. Device-Independent Bitmap Formatted asa Disk File 

store them to disk. If you examine the 

disk file, you will notice that the bitmaps are stored in DIB format. Howéver, if you include bitmap files created with 
SDKPaint in an application's resource file, and load them with LoadBitmap(), the resultant bitmap is in ae old DDB 
format in memory. What happened? 

To maintain compatibility with applications written under Windows 2.2 versions, LoadBitmap() w was set up to 
automatically convert DIB bitmap data to the DDB bitmap format. This is convenient, as it means that you can use 
both old and new bitmap files as resource data in a Windows 3.x application. 

The problem with LoadBitmap()’s conversion from DIB to DDB format is that you iiss the color information 
stored with the DIB data. If the bitmap was stored with 256 colors, and is to be displayed on a 256 color system, you 
will still be able to use only the 20 reserved system colors when the bitmap is displayed. The way around color informa- 
tion loss is to load the color information from the bitmap’s header separately. LoadBitmap() will not do this for you. 
Instead, use FindResource(), LoadResource(), and LockResource() to return a handle to a locked memory block 
containing the BITMAPINFO data structure. As discussed in the previous section, that amounts to a BITMAPINFO- 
HEADER structure, followed by an array of RGBQUAD data structures that contain the actual colors. 

_ With access to the color data from the BITMAPINFO data header, the application can create a logical palette that 
matches that specified in the bitmap. The steps involved are 
1. Use FindResource(), LoadResource(), and LockResource() to obtain a handle to a memory block containing the 
DIB data. 


Examine the biBitCount and biClrUsed fields to determine the number of colors stored in the DIB data. 
Retrieve the color entries from the RGBQUAD array. 

Create a logical palette with the DIB colors by calling CreatePalette(). 

Select the palette into the device context, by calling SelectPalette(). 

Realize the palette by calling RealizePalette(). 

Call SetDIBitsToDevice() or StretchDIBits() to transfer pe image to the device contoxt. 
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DIB Example 


Listing 15-1 shows an example of loading the color data from a DIB, and thiad displaying the bitmap. The example 
assumes that the PEN.BMP DIB bitmap file was. made part.of the resource script data with a line like | 


pen . BITMAP pen.omp 


The color data from the DIB is read and converted to a logical palette when the WM_ CREATE message is pro- 
cessed. This procedure gets a little involved, as the program has to calculate how many color values are stored with 
the bitmap. Note that although the logical palette i is created while processing the WM_CREATE message, it is not 
realized until the WM_PAINT message is processed. 

_ The SetDIBitsToDevice() function is used to display the bitmap. This function requires a pointer to both the 
BITMAPINFO data and the DIB bitmap data. The latter is calculated as an offset from the start of the BITMAPINFO 
data, as the resource data loads the bitmap bits right after the end of the color data. 


oS Listing 15-1. Example Loading a DIB Bitmap 
tong FAR PASCAL WndProc CHWND hWnd, unesened iMessage, WORD wParam, LONG lParam) 


static HANDLE 7 hRes, hPal ; 


‘static LPBITMAPINF LpBitmzsinfo ; 
LPLOGPALETTE ' tpLogPalette ; 
static HPALETTE 2 hPalette ; 
LPSTR LpBits : 

int ; : ees eee ; 
static int = nColorbata ; 
PAINTSTRUCT PS > 


WINDOWS AP! BIBLE | 


switch CiMessage) /* process windows messages */ 
cf 25 


case WM_CREATE: 

/* Load DIB, and get handle to its Cocked's mem. block */ 
hRes = LoadResource (ghInstance, 
FindResource (ghInstance, "pen", RT_BITMAP)) ; 
LpBitmapInfo = (LPBITMAPINFO) LockResource cnneay 

/* calculate the number of. Slee data entries in DIB */ 

if (LpBi tmapInfo->bmiHeader. biClrUsed != 0) 
nColorData = (pBitmapInfo->bmiHeader.biClrUsed ; 


else 
{ 
switch SPRE SMeREnton beiisadee. biBitCount) 
{ 
case 1: 
: nColorDdata = 2 ; /* monochrome */ 
break ; 
case 4: 
nColorData = 16 ; /* typical vga */ 
break ; ; 
case 8: 
nColorbData = 256; /* 256 colors */ 
break ; 
case 24: . ; 
- nColorData = 0 ;/* rgb encoded for */ 
break ; /* every pixel in bitmap */ 
} 
} 


/* allocate memory to hold palette */ 
hPal = GlobalAlloc (GMEM_MOVEABLE, sizeof (LOGPALETTED + 
; (nColorData * sizeof (PALETTEENTRY))) ; 
LpLogPalette = (LPLOGPALETTE) GlobalLock Chats ; 

- /*® create the logical palette */ 
LpLogPalette->palVersion = 0x300 ; /* Windows 3.0 */ 
lpLogPalette->palNumEntries = nColorData ; 

/* load each color into palette fields */ 
for (i = 0; i < nColorData ; i++) 


lLpLogPalette->palPalEntry CiJl.peRed = 
var : lpBitmapInfo->bmiColors CiJl.rgbRed ; 
LpLogPalette->palPalEntry Cil.peGreen = 
LpBitmapInfo->bmiCcolors Cil.rgbGreen ; 
LpLogPalette->palPalEntry Cil.peBlue = 
: LpBitmapInfo->bmiColors Cil.rgbBlue ; 


} /* create the palette */ 
hPalette = CreatePalette (lpLogPalette) ; 
GlobalUnlock ChRes) ; 
GlobalUnlock aneat) : 
GlobalFree (hPal) ; ~ 
break ; 
case WM_. PAINT: 
BeginPaint (hwnd, &ps) ; 
SelectPalette (ps.hdc, hPatette, FALSE) ; 
RealizePalette (ps.hdc) ; /* put palette into action */ 
/* get handle to ‘DIB, reloading if necessary 1 
_hRes = LoadResource (ghInstance, 
FindResource (ghInstance, “pen", RT_BITMAP)) ; 
LpBitmapInfo = (LPBITMAPINFO) LockResource (hRes) ; 
_ /* find address of the bitmap data */_ 
lpBits = (LPSTR) LpBitmapInfo ; 
LpBits += (WORD) LpBitmapInfo->bmiHeader.biSize + 
CWORD) (CnColorData * sizeof (RGBQUAD)) ; 
/* display the bitmap on the window's client area */ 
SetDIBitsToDevice (ps.hdc, 10, 10, 
CWORD) LpBitmapInfo->bmiHeader .biWidth, 
CWORD) LpBitmapInfo->bmiHeader.biHeight, 


o ao z 
0, (WORD) LpBitmapInfo->bmiHeader .biHeight, 
tpBits, LpBitmapInfo, DIB_RGB_COLORS) ; 
= ‘ GlobalUnlock ChRes) ; 
EndPaint. (hWnd, &ps) ; 
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‘break ; 


case WM_COMMAND: /* process menu items */ 

switch (wParam) 

t 

case IDM_QUIT: /* send end on application message */ 
DestroyWindow ChwWnd) ; 
break ; 

} 

break ; 

/* stop application */ 

DeleteObject (hPalette) ; 

FreeResource (ChRes) ; 

PostQuitMessage (Q) ; 

break ; 


default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
} 
return (QL) ; 
} 
Bitmap Function Summary 


Table 15-3 summarizes the bitmap functions. The detailed function descriptions are in the next section. 


BIBI 

Create Bitmap | 
CreateBitmapindirect 
CreateCompatibleBitmap 
CreateDIBitmap 
CreateDIBPattemBrush 
CreateDiscardableBitmap 


GetBitmapBits 
GetBitmapDimension 


GetDIBits 
GetStretchBitMode 
LoadBitmap 

PatBlt 
SetBitmapBits 
SetBitmapDimension 


SetDIBits 
SetDIBitsToDevice 
SetStretchBitMode 
StretchBit 


‘StretchDIBits- 


ces a sine from a memory device context to another device context. 
Creates a DDB bitmap based on an array of color bit values. 
Creates a DDB bitmap based on data in a BITMAP data structure. 
Creates a memory bitmap compatible with a device. 
reates a memory bitmap based on device-independent bitmap (DIB) data. . 
Creates a pattern brush based on a device-independent bitmap stored in a global memory block. 


Creates a DDB bitmap compatible with a device. Windows can discard the bitmap data if the 
bitmap is not selected. 


Loads the bitmap data into a memory block. 

Retrieves two values that were associated with the bitmap by a previous call to 
SetBitmapDimension(). 

Fills in BITMAPINFO data for a DIB, and/or writes a DIB’s pixel data into a memory buffer. 
Determines the current bitmap stretching mode of a device context. 

Loads a bitmap resource into memory. 

Outputs a pattern brush to a device. 


Sets the pixel data for a DDB bitmap. 


Sets two values that are associated with the bitmap. These as can be retrieved later using 
GetBitmapDimension(). 


Sets device-independent bitmap (DIB) pixel data to the data in a memory buffer. 

Paints from a device-independent bitmap (DIB) directly on a device context. - 

Sets the bitmap stretching mcde for the StretchBit() function. 

Copies a DDB bitmap from one device context to another, stretching or contracting thei image to 
fit the destination rectangle. : 
Paints from a DIB directly on a device context, stretching and/or compressing the image as it is 
painted. . 


Table 15-8. Bitmap Function Summary. 
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Bitmap Function Descriptions 
This section contains descriptions for the esate functions. 


BrrBur 


‘Description | 


BLACKNESS. 
DSTINVERT 
MERGECOPY 

MERGEPAINT 


| mWin20 ) @Win30 mw Win3.1 
Copies a bitmap from a memory device context to another device context. 


BOOL BitBit(HDC ADC, int X, int ¥, int nWidth, int nHeight, HDC hSrcDC, int XSre, int YSre, 
DWORD dwRop); 


The bitmap must first be selected into a memory device context, ‘geeated with 
CreateCompatibleDC(). Normally, the bitmap is copied without modification. The bitmap can be 
combined with the existing background using any of the raster-operation codes if desired. The 
source bitmap is stretched or compressed to match the dimensions of the destination. Not all 
devices support BitBlt(). Use GetDeviceCaps() to check if BitBit() operations are supported. 


This is the standard function for copying a bitmap to a le 
BOOL. Nonzero if the function was successful, zero on error. 


PatBit(), CreateCompatibleDC(), DeleteObject(), LoadBitmap(), SletOiet, GetDevice- 
Caps() 


HDC: The device context handle to receive the bitmap. 

int: The logical X coordinate of the upper left corner of the destination rectangle. 

int: The logical Y coordinate of the upper left corner of the destination rectangle. | 
int: The width, in logical units, of the destination rectangle. | 


‘int: The height, in logical units, of the destination rectangle. 


HDC: The device context from which the bitmap will be copied. This is normally a memory device 
context created with CreateCompatibleDC(). A bitmap is loaded into the mertiory device context 
using SelectObject(). hSrcDC must be NULL if the dwRop parameter does not require a source 
bitmap. For example, the BLACKNESS, WHITENESS, and DSTINVERT options operate solely on 
the background of the destination device context. 


int: The logical X coordinate of the upper left corner, in the source bitmap. Normally 0, for the 
whole bitmap. 


"int: The logical Y coordinate of the upper ht corner in the source bitmap. Normally 0, for the 
_ whole bitmap. 


-DWORD: One of the raster-operation codes. Fifteen of the 256 possibilities have names defined 


in WINDOWS.H and are listed in Table 15-4. The remainder have hexadecimal codes, specified in 
Volume 2, Section 11, Table 11.3 of the Microsoft SDK Reference manuals. These codes deter- 
mine how the colors of the brush are combined with the existing colors of the background. For 
the Boolean codes, “S” is the source bitmap, “D” is the destination bitmap, and “P” is the cur- 
rently selected brush (called a “pattern”) of the device context. The Boolean sais in Table 
15-4 follow the C language conventions. 


“Tums al output black 0) 
Inverts the destination bitmap. (~D) . 
_ The source and destination bitmaps are combined with the Boolean AND operator. (D & S) 


The source and destination bitmaps are combined with the Boolean OR operator. (~S | D) 
/ : ; 
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NOTSRCCOPY Inverts the source bitmap, then copies it to the destination. (~S) 
NOTSRCERASE __ Inverts the result of combining the source and destination bitmaps using the Boolean OR 
operator. (~(S I D}) 
PATCOPY Copies the pattern to the destination. (P)_ 
PATINVERT Combines the destination bitmap with the pattem using the Boolean XOR operator. (P “ D) 
PATPAINT | “Pl ~(SID) | 
SRCAND Combines the source and destination bitmaps with the Boolean AND operator. (S & D) 
SRCCOPY Copies the source to the destination. (S) 
SRCERASE $&~D- 
SRCINVERT Combines the source and destination bitmaps using the Boolean XOR operator. (S 4 D) 
SRCPAINT Combines the source and destination bitmaps using the Boolean OR operator. (S | D) 
WHITENESS . Turns ail output white. This is a quick way to blank a device context. (1) 

Table 15-4. Raster-Operation Codes. - 

Example This example (see Figure 15-4) copies a bitmap to the window's 


client area when the user clicks the “Do It!” menu item. 

The resource script file loads a bitmap file. The PEN.BMP 
file is a 60 by 60 pixel color bitmap reated with the nar 
SDKPaint application. 


> GENERIC.RC Resource Script File 


/* generic.rc */ . 


#include <windows.h> 


#include “generic.h” ; Saas 
generic. ICON generic.ico — . aX Figure 15-4. Budi) 
pen BITMAP pen.bap ‘ Example. 
generic MENU \ \ 
BEGIN i 
RENUITEM "“&Do itr : IOM_DOIT 
MENUITEM reeutet, : IDM_ aulT 
END 


The “pen” bitmap is loaded into memory when the WM_! CREATE message is processed. The 
bitmap is copied to the client area device context when the user clicks the “Do It!” menu item. 
Note that the pen is is deleted from memory as the ae exits (WM_DESTROY message 


processed). 
. Long FAR PASCAL WndProc CHWND hwnd, unsigned iMessage, woRD wParam, LONG LParam) 
: static . | HBITMAP hBitmap ; 
HOC. ‘ hoc, hMemDC ; 
avitch CiMessage) . f* process windows messages */ 


case WM_CREATE: , 
hBitmap = LoadBitmap (ghInstance , “pen") ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 


{ 
case IDM_DOIT: /* User hit the “Do it" menu item */ 


- hDC = GetDC Chuind) ; 
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static 
HDC 
static 


. hMemDC = CreateCompatiblepc Chbc) ; 
“SelectObject (hMemDC, hBitmap) ; 
BitBtt Choc, 10, 10, 60, ad hMembC, 0, 0, 
SRCCOPY) ; 
DeletedC ChMemDC) ; 
ReleaseDdC (hWnd, hoe) 7 
break ; 
case IDM_QUIT: /* send end of application message */ 
. DestroyWindow ChWnd) ; 
break ; : 
} 
break ; 
case WM_DESTROY: 
DeleteObject (hBitmap) ; 
PostQuitMessage (0) ; 
break ; 
default: 


/* stop application */ 


/* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 


} 
return (OL) ; 
} 
CREATEBITMAP gWin2.0 wWin3d.0 em Win3l 
Purpose Creates a DDB bitmap based on an array of color bit values. 
Syntax HBITMAP CreateBitmap(int nWidth, int anes BYTE ee BYTE nBitCount, LPSTR 
lpBits); 
Description This function creates a bitmap based on the array of color bit data pointed to by lpBits. 
Uses Not often used. Normally, bitmaps are created using the SDKPaint application and loadea as part 
_ of the application’s resource data. See LoadBitmap() for an example. 
Returns HBITMAP, the bitmap handle. NULL on error. 
See Also CreateBitmapIndirect(), SelectObject(), DeleteObject(), SetBitmapBits() 
Parameters | | 
nWidth int: The width, in pixels, of the bitmap. 
nHeight int: The height, in pixels, of the bitmap. 
nPlanes int: The number of color planes in the bitmap. This is used for devices (such as video boards) that 
specify colors with color planes. Each plane will need nWidth * nHeight bits. 
nBitCount int: The number of color bits per display pixel. Either nPlanes a ER NEERTORTTETSEY 
ornBitCount will be set to one in all cases. s. For black and white varicliw, ; 
bitmaps, both are set to one. : 
[pBits LPSTR: A pointer to an array of byte values jitaitins the Do it Quit | 
pixel data. For black and white bitmaps, 0 is for black and 1 is | E 
for white. For color bitmaps, the colors are device dependent. 
IpBits can be set to NULL. Use SetBitmapBits() to initialize Eon: mi 
. the bitmap data. Figure 1 5. 5. CreateBitmap( ) 
Example This example (see Figure 15-5) paints a small bitmap ‘ coor. “xample. 


dinates 10,10 in the upper left corner of the window's client 
area when the user clicks the “Do It!” menu item. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


HBITMAP hSitmap ; 

_ ADC, hMembC ; 
BYTE BitMapBits C] = { a ial define bitmap pattern + 
0x00, Qx00, 0x00, 0x00, ; 


0x00, 0x00, 0x00, 0x00, 
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OxOf, Oxff, Oxff, Oxf0, 
OxOf, Ox7f, Oxfe, Oxf0, 
OxOf, Ox7f, Oxfe, Oxf0, 
OxOf, Ox7f, Oxfe, Oxf0, 
OxOf, 0x00, 0x00, OxfO, 
OxO0f, Ox7f, Oxfe, Oxf0, 
Ox0f, Ox7f, Oxfe, Oxf0, 
OxOf, Oxff, Oxff, Oxf0, 
0x00, 0x00, 0x00, 0x00, 
0x00, 0x00, 0x00, 0x00 } ; 


switch (iMessage) /* process windows messages */ 
{ 


case WM_CREATE: 
ile CreateBitmap (32, 12, 1, 1, BitMapBits) ; 
break ; , 

case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
hDC = GetDC ChWnd) ; 
hMemDC = CreateCompatibleDC ChDC) ; 
SelectObject ChMemDC, hBitmap) ; 
BitBlt (hDC, 10, 10, 32, 12, hMemDC, 0, 0, SRCCOPY) ; 
DeleteDC ChMemDC) ; 
Releasedc ChWnd, hDC) ; 


break ; 
case IDM_QUIT: /*® send end of application message a] 
DestroyWindow (hWnd) ; 
break ; — 
} 
break ; 
case WM_DESTROY: - /* stop application */ 


DeleteObject (hBitmap) ; 

PostQuitMessage (0) ; \ 

break ; a 
defaults: /* default windows message processing */ 

return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 


} <6 
return (OL) ; 


} 
CREATEBITMAPINDIRECT wWin20 8Win3d.0 mWin31 
Purpose . Creates a DDB bitmap based on data in a BITMAP data structure. 
Syntax HBITMAP CreateBitmapIndirect(BITMAP FAR * lpBitmap); 
Description . The BITMAP data structure is defined in WINDOWS.H as 
typedef struct tagBITMAP 
{ car F 
int bmType; /* set to zero */ 
int bmWidth; /* pixel width */ 
int bmHeight; /* pixel height */ 
int bmWidthBytes; /* no bytes per row */ 
BYTE ' bmPlanes; = /* no. color plains’ */ 
BYTE bmBitsPixel; : /* color bits/pixel */- 
LPSTR bmBits; /*®* pointer to bit data */ 
> BITMAP; 
typedef BITMAP *PBITMAP; 
typedef BITMAP NEAR *NPBITMAP; 
typedef BITMAP FAR *LPBITMAP; 


Fill in this data structure and call CreateBitmapIndirect() as an alternative to calling Create- 
Bitmap(). The bmBits element should be set to point to an array of byte values containing the 
bitmap data. For black and white bitmaps, zero is black and 1 is white. For color bitmaps, the 
colors are device dependent. 
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Uses Not often used. N ormally, bitmaps are created using the 
SDKPaint application, and loaded as part of the application’s 
resource data. See LoadBitmap() for an example. 


Returns _ HBITMAP, the bitmap handle. NULL on error. 
See Also '  CreateBitmap(), SelectObject(), DeleteObject() . 
Parameters — 
lpBitmap. BITMAP FAR *: A far pointer to a bitmap data structure Figure 15-6. CreateBitmap- 
= (shown above). Indirect() Example. 

Example This example, as shown in Figure 15-6, paints a small, rectan- 

gular bitmap in the upper left corner of the window’s client area when the user clicks the “Do It!” 

menu item. 


e 


long FAR PASCAL WndProc CHWND hWnd, unsigned ‘iiceeades WORD wParam, LONG lParam) 
{ 


static - HBITMAP hBitmap ; 

HDC hDC, hMemDC ; 
BITMAP ; bitmap ; : 

static BYTE BitMapBits CJ = ¢ /* define bitmap pattern */ 


0x00, 0x00, 0x00, 0x00, 
0x00, 0x00, 0x00, 0x00, 
OxOf, Oxff, Oxff, Oxf0, 
Ox0f, Oxff, Oxff, Oxf0, 
OxOf, Oxff, Oxff, OxfO, 
OxOf, Oxff, Oxff, Oxf0, 
OxOf, Oxff, Oxff, Oxf0, 
OxOf, Oxff, Oxff, Oxfd, 
OxOf, Oxff, Oxff, Oxf0, 
OxOf, Oxff, Oxff, Oxf0, 
0x00, 0x00, 0x00, 0x00, 
0x00, 0x00, 0x00, Ox00 } ; 


switch (iMessage) , /* process windows messages */ 


case WM_CREATE: 
bitmap.bmType = 0 ; 
bitmap.bmWidth = 32 ; 
bitmap.bmHeight = 12 ; 

' bitmap.bmWidthBytes = 4 ; 
bitmap.bmPlanes = 1 ; 
bitmap.bmBitsPixel = 
bitmap.bmBits = (LPSTR) BitMapBits ; 
hBitmap = CreateBitmapIndirect ¢ 

(BITMAP FAR *) &bitmap) ; 
break ; : ee 
case WM_COMMAND: : /* process menu items */ 
switch (wParam) a 


case IDM_DOIT: /* User hit the “Do it" menu item */ 
oe hDC = GetDC ChWnd) ; 
hMemDC = CreateCompatibleDCc (hDC) ; 
SelectObject (hMemDC, hBitmap) ; 
BitBlt ChDC, 10, 10, 32, 12, hMemDC, 0, 0, 
SRCCOPY) ; 
DeleteDC (hMemDC) ; 
ReleaseDC ChWnd, hoe : 


break ; 
case IDM_QUIT: /* mend end of application mersags * 
Dest roylindow <nndy? 
break ; 
}. 
break; 
case WM_DESTROY: , |* stop application */ 


. Deletedbject ChBitmap) ; 
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PostQuitMessage (0) ; 
break ; 

default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; 


? 

CREATECOMPATIBLEBITMAP qWin20 eWin30 mWin31 

Purpose Creates a memory bitmap that is compatible with a device. 

Syntax HBITMAP CreateCompatibleBitmap(HDC ADC, int nWidth, int nHeight); 

Description This function creates a memory bitmap with the same number of color panes z.ad the same num- 
ber of color bits per pixel as the device specified by ADC. Bitmap can then be selected into a 
memory device context and drawn upon. 

‘The bitmap memory area is not initialized when created. It will be filled with random bytes 
and can be converted to a solid culor by using a GDI function, such as Rectangle() or PatBIt(), to 
paint the memory device context. 

Uses Memory device contexts and compatible bitmaps allow an application to draw a complex figure in 

"memory, and then quickly copy it to a physical device using BitBltQ) and similar functions. This 
technique can be more attractive than letting an image appear in sections on the screen. It is also 
an efficient way to draw small repeating patterns (see the following example). 

Returns HBITMAP, the handle of the bitmap created. Returns NULL on error. 

See Also CreateCompatibleDC(), CreateDiscardableBitmap() 

Parameters | 

hDC HDC: The device context handle for the physical device with (AaReuEy srs mace ae 

: which the bitmap is to be compatible. Typically, thisisahandle agama. e[~. [-, 
to the window's client area device context, retrieved by either cE 
GetDCQ) or BeginPaint(). : | Do tt "au it 
nWidth int: The width, in pixels, to which the bitmap is to be initial- 
ized. 
nHeight int: The height, in pixels, to which the bitmap is to be initial- 
Example This example, shown in Figure 15-7, draws three identical pat- 


terns on the window’s client area when the user clicks the “Do 
It!” menu item. Rather than use the GDI painting functions for 
each of the drawings, the application draws the pattern to a 
memory device context containing a bitmap compatible with 
the screen. As soon as that pattern is painted to the memory 
device context, the pattern can be copied to the window's cli- Figure 15-7. CreateCom- 
ent area efficiently using BitBlt(). Note that similar efficien- patibleBitmap() Example. 
cies could have been obtained using a metafile. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ Ba 


static HBITMAP hBitmap ;. 
HDC hDC, hMemDC ; 
int i; 
switch CiMessage) /* process windows messages */ 
4 
case WM_COMMAND: /*-process menu items */ 


~ switch (wParam) 


' 
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{ 
case IDM_DOIT: /* first create a memory de */ 

hDC = GetDC (hWnd) ; 
hMem0C = CreateCompatibledc ChDC) ; 
hBitmap = CreateCompatibleBitmap choc, 

50, 50) ; 

/* paint on memory device context */ 
SelectObject (hMemDC, hBitmap) ; 
SelectObject ChMemDC, GetStockObject (BLACK_BRUSH)) ; 
Rectangle (hMemDC, 0, 0, 50, 50) ; 
SelectObject (hMemDC, GetStockObject CWHITE_BRUSH)) ; 
Ellipse (hMempDC, 0, 0, 50, 50) ; 
Rectangle (hMemDC, ey 5, 45, 45) 7 
Ellipse (hMemDC, 10, 10, 40, 40) > 
SelectObject (hMemDC, GetStockObject (BLACK, BRUSH)) ; 
Rectangle (hMem0C, 15, 15, 35, 35) ; 

/* now copy the memory device context to screen */ 
for (i= 0; i1<3 ;itt) 

BitBLe Choc, 0, 50 * i, 50, 50 + (50 * i), 

hMemDC, 0, 0, SRCCOPY) ; 

DeleteDC ChMemDC) ; 
DeleteObject (hBitmap) ; 
ReleaseDC ChWnd, hDC) ; 


break ; 
[Other program lines] 
CreaTEDIBITMAP : OWin2.0 mWin3.0 mWin3l 
Purpose Creates a memory DDB bitmap based on device-independent bitmap (DIB) data. - 
Syntax HBITMAP CreateDIBitmap(HDC hDC, LPBITMAPINFOHEADER lpInfoHeader, DWORD 
. dwUsage, LPSTR lpInitBits, LPBITMAPINFO lpJnitInfo, WORD wUsage); 
Description The CreateDIBitmap() function creates a memory DDB bitmap based on data in several data 


structures. The primary structure is BITMAPINFO, defined in WINDOWS.H as 


typedef struct tagBITMAPINFO ¢ 
BITMAPINFOHEADER bmiHeader; 
RGBQUAD : bmiColorsf[1]; 

} BITMAPINFO; 

typedef BITMAPINFO FAR *LPBITMAPINFO; 

typedef BITMAPINFO *PBITMAPINFO; 


BITMAPINFO contains two other structures, BITMAPINFOHEADER and RGBQUAD, also defined 
in WINDOWS.H. 


© The BITMAPINFOHEADER Structure 
._ typedef struct tagBITMAPINFOHEADERL 


DWORD biSize; /* size of BITMAPINFOHEADER */ 
DWORD biWidth; | /* width in pixels */ 
DWORD biHeight; /* height in pixels */ 
WORD biPlanes; /* always 1 */ 
WORD biBitCount; /* color bits per pixel */ 
/* must be 1, 4, 8 or 24 */ 
DWORD biCompression; /* BI_RGB, BI_RLE8 */ 
/* or BI_LRLES */ 
DWORD biSizeImage; /* total bytes in image */ : 
DWORD . bixPelsPerMeter; /* 0, or opt. h res.-*/ 
DWORD biYPelsPerMeter; /* 0, or opt. vres. */ 
DWORD biclrUsed; /* normally Q, can set a */ 
/* Lower no. colors than biBitCount me 
DWORD biClrimportant; /* normally O */ 


} BITMAPINFOHEADER; 


typedef BITMAPINFOHEADER FAR *LPBITMAPINFOHEADER; 
typedef BITMAPINFOHEADER *PBITMAPINFOHEADER; : 
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> RGBQuad Structure 


typedef struct tagRGBQUAD { 
BYTE rgbSlue; 
BYTE rgbGreen; 
BYTE rgbRed; 
BYTE rgbReserved; 


} RGBQUAD; | | 
Uses There are two ways to use CreateDIBitmap(). If dwUsage is set to NULL, an uninitialized DIB 
' bitmap is created. This is the first step in using the DIB with a memory device context. IfdwU/sage 

is set to CBM_INIT, CreateDIBitmap() is used to create a complete DDB bitmap. Data is passed 
to the function for all color values and header settings. 

Returns HBITMAP, a handle to the bitmap created. NULL on error. 

See Also GetDIBits(), CreateBitmap() 

Parameters 

hDC HDC: The device context of the physical device to which the bitmap will be mapped. Typically, 


this is the window’s client area device context, retrieved with either GetDC() or BeginPaint(). 
lpInfoHeader LPBITMAPINFOHEADER: A pointer to a BITMAPINFOHEADER data structure. The values in 
this structure must be set before CreateDIBitmap() is called. These values determine the size 
and color resolution of the bitmap. 
dwUsage DWORD: Determines if CreateDIBitmap() creates an initialized or uninitialized bitmap. If NULL, 
the bitmap is created uninitialized, and the following three parameters should be set to NULL. If 
dwUsage equals CBM_INIT, the bitmap is initialized based on the data pointed to by [p/nitBits 


and lpInitInfo. 
lpInitBits LPSTR: A pointer to an array of bitmap pixel color values. The format will depend on the color 
resolution of the device, as specified in the BITMAPINFO data pointed to by [p/nitInfo. 
ipInitInfo LPBITMAPINFO: A pointer to a BITMAPINFO data structure eae the data format used in 
IpInitBits. . 


wUsage WORD: Specifies if the bmiColors/] fields in the lpInitInfo 

data structure contain explicit RGB values, or if they are 16-bit 
indexes, to the currently realized logical palette. 
DIB_PAL_COLORS specifies palette entries. DIB_RGB_COLORS 
specifies explicit colors. 


Example This example paints a small globe image on the window’s cli- 
ent area when the user clicks the “Do It!” menu item. The im- _bacsscmssmcemceemccemecmenn 
age shown in Figure 15-8 is created by painting ona memory Figure 15-8. CreateDIBit- 
device context containing a 50 by 50 pixel DIB bitmap. The map() Example. 
bitmap is then copied to the screen using BitBIt(). 


long FAR PASCAL WndProc CHWND hWnd, unsigned. iMessage, WORD wParam, LONG lParam) 
{ 


BITMAPINFOHEADER bi ; 
BITMAPINFOHEADER FAR *lpbi ; 
HBITMAP hBitmap ; 
HDC hDC, hMemDC ; 
HANDLE hDIB ; 
switch (iMessage) /* process windows messages */ 
{ 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 
{ 


case IDM_DOIT: 
hDC = GetDC ChWnd) ; 


683 


WINDOWS API BIBLE 


/* initialize BITMAPINFOHEADER data */ 
bi.biSize = sizeof (BITMAPINFOHEADER) ; 
bi.biWidth = 50 ; /* 50 by 50 bitmap */ 
bi.biHeight = 50 ; 
bi.biPlanes = 1 ; 


bi.biBitCount = 4; /* 16 colors on screen */ 
i - bi.biCompression = BI_RGB ; /* no compression */ 
bi.biSizeImage = 0 ; : 
bi.bixPelsPerMeter = 0 ; 
bi.biYPelsPerMeter = 0 ; 


bi.biclrUsed = 0 ; 
bi.biClrimportant = 0; 
/* create uninitialized DIB bitmap */ 
hBitmap = CreateDIBitmap C(hDC, &bi, OL, 
NULL, NULL, 0) ; 
/* allocate memory for BITMAPINFOstruct */ 
hDIB = GlobalALloc (GHND, 
sizeof (BITMAPINFOHEADER) + 
16 * sizeof (RGBQUAD)) ; 
Lpbi = (BITMAPINFOHEADER FBR *) 
GlobalLock ChDIB) ; 
/* copy bi to top of BITMAPINFO */ 
*lpbi = bi ; 
/* use GetDIBits() to init bi struct data */ 
GetDIBits ChDC, hBitmap, 0, 50, NULL, 
(LPBITMAPINFO) Lpbi> DIB_RGB_' COpgR >? 
GlobalUnlock (hDIB) ; 
/* create memory device context */ 
hMemDC = CreateCompatibleDC ChDC) ; 
/* select DIB bitmap into Fevice context */ 
SelectObject (hMemDC, hBitmap) ; 
/* paint on memory device context */ 
SelectObject (hMemDC, GetStockObject 
(BLACK_BRUSH)) ; 
Rectangle (hMemDC, 0, 0, 50, 50) ; 
SelectObject (hMemDC, GetStockObject 
CWHITE_BRUSH)) ; 
Ellipse ChMemDC, 0, 0, 50, 50) ; 
Ellipse (hMemDC, 10, 0, 40, 50) ; 
Ellipse (hMemDC, 20, 0, 30, 50) ; 
/* copy the memory dec to screen */ 
BitBlt ChodC, 0, 0, 50, 50, hMemDC, 0, 0, 
SRCCOPY) ; 
DeleteDC (hMemDC) ; 
GlobalFree (hDIB) ; 
ReleaseDC ChWnd, hDC) ; 
break ; 


[Other program lines] 


CrEATEDIBPATTERNBRUSH OWin20 eWin30 gWin3.1 
Purpose Creates a pattern brush based on a device-independent bitmap stored in a global memory block. . 
Syntax : HBRUSH CreateDIBPatternBrush(HANDLE hPackedDIB,WORD wUsage); 


Description This function works by passing a handle to a memory block containing both the BITMAPINFO 
structure data and the pixel data for the bitmap. The memory block is read and converted to a . 
brush pattern that can be selected into a device context for painting. 


Uses | Using a DIB pattern brush provides a way to ensure that the colors will not end up drastically 
different when displayed on a different device. See the example program at the re of this 
chapter for how to use the DIB color data to realize a logical palette. 


Returns HBRUSH, a handle to the brush created. NULL on error. 
See Also. GetDIBits(), CreateDIBitmapQ) 
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Parameters 
hPackedDIB - 


wUsage 


Example 


GLOBALHANDLE: The handle of a global memory block (allocated with GlobalAlloc()) that 
contains the bitmap data. The memory block must contain an initialized BITMAPINFO data struc- 
ture at the beginning, followed immediately by the bitmap bytes. The size of the bitmap data will 
depend on the color resolution and the height/width of the bitmap. Each line of the bitmap data 
must terminate on an even DWORD address (an even 32 bits). This requirement will extend the 
size of the memory area needed if the bitmap size (width * color bits) does not end on an even 32- 


bit boundary. 


WORD: Specifies whether the bmiColors/] fields at the end of the BITMAPINFO data structure 
contain explicit RGB color values, or if they are indexes into the currently realized logical pal- 
ette. wUsage can be either DIB_PAL_COLORS for palette colors, or DIB_LRGB_COLORS for ex- 


plicit RGB colors. 
This example, illustrated in Figure 15-9, creates a device-inde- 


- ,pendent bitmap, and uses it.as a brush to paint a square area. 


The DIB is created uninitialized, and then painted in a memory 
device context. Once painted, the pixel data is copied to the 
end of the memory buffer containing the BITMAPINFO data. 
The memory block containing both the BITMAPINFO data fol- 
lowed by the bitmap pixels is read by CreateDIBPattern- 
Brush() to create the pattern brush. Once the pattern is 
selected into the device context, painting a rectangle results 
in the area being filled with the DIB pattern. 

Note that the ALIGNLONG macro is defined to help com- 
pute even DWORD address lengths for the storage of the 
bitmap data. For simplicity, this example assumes a 16-color 
device context. This example also omits error checking for 
memory allocation. . 


‘ddefine ALIGNLONG(4) (C443) /4%4) 
8 


Hdefine WIDTH 
#define HEIGHT 


8 


4#define COLORBITS 4 


‘= generic [~ [> 
PDolt! Qut — | 


Figure 15-9. CreateDIB- 
PatternBrush{) Example. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ : 


static BITMAPINFOHEADER bi ; 
LPBITMAPINFOHEADER Lpbi ; 
HBITMAP hBitmap ; 
HDC hDC, hMemDC ; 
HANDLE hDIB ; 
HBRUSH hDiIBrush ; 
LPSTR- lpstBitmap ; 


switch CiMessage) 
{ 


/* process windows messages */ 


case WM_COMMAND: /* process menu items */ 
eo 


switch (wParam) 
{ 


case IDM_DOIT: 
hDC = GetDC ChWnd) ; 


/* initialize BITHAPINFOHEADER data */ 
bi.biSize = sizeof (BITHAPINFOHEADER) ; 
bi.biWidth = WIDTH ; /* 8 by 8 bitmap */ 


bi.biHeight = HEIGHT ; 
bi.biPlanes = 1; 


: 
bi.biBitCount = COLORBITS ; /* 16 colors */ 


685 


WINDOWS API BIBLE 


\ 


bi.biCompression = BI_RGB ; 
bi.biSizeImage = 

CALIGNLONG(CWIDTH * COLORBITS)/8) * HEIGHT); 
bi.bixPelsPerMeter 
bi. biyPelsPerteter 
bi.biclrUsed =O; 
bi. biClrImportant = 0; 

/* create intnitialived DIB bitmap */ 
hBitmap = CreateDIBitmap ChDC, &bi, OL, NULL, 

NULL, O) ; 

/* allocate memory for BITMAPINFO structure */ 
hDIB = GlobalAlloc (GHND, sizeof (BITMAPINFOHEADER) + 

16 * sizeof (RGBQUAD) + 

CALIGNLONGCCWIDTH * COLORBITS)/8) * HEIGHT)); 
Lpbi = (BITMAPINFOHEADER FAR *) GlobalLock C(hDIB) ; 

/* tricky way to copy bi to top of BITMAPINFO */ 
*Lpbi = bi >; 

/* use GetDIBits() to init tpbi struct data */ 
GetDIBits (hDC, hBitmap, 0, 50, NULL, 

(LPBITMAPINFO) ipbi, DIB_RGB_COLORS) ; 
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0; 


/* create memory device context */ 
hMemDC = CreateCompatibleDC ChDC) ; 

/* select DIB bitmap into device context */ 
SelectObject (hMemDC, hBitmap) ; 

/* paint.on memory device context */ 
SelectObject (hMemDC, GetStockObject (BLACK_BRUSH)) ; 
Rectangle ChMemDC, 0, 0, WIDTH, HEIGHT) ; 
SelectObject (hMemDC, GetStockObject (WHITE_BRUSH)) ; 
Ellipse (hMemDC, 0, 0, WIDTH, HEIGHT) ; 

/* set pointer to bitmap's bit data */ 
LpstBitmap = (LPSTR) Lpbi + 

(WORD) sizeof (BITMAPINFOHEADER) + 

(16 * sizeof (RGBQUAD)) ; 

GetDIBits (hDC, hBitmap, 0, HEIGHT, LpstBitmap, 

(LPBITMAPINFO) Lpbi, DIB_RGB_COLORS) ; 


/* now use DIB as pattern brush */ 
hDIBrush = ChesteDlerarternBrusn ChDIB, 
DIB_RGB _ COLORS) ; 
SelectObject (hdc, RDEBrGsh) <3 
PatBlt Chbdc, 0, 0, 100, 100, PATCOPY) is 


GlobalUnlock (hDIB) ; 
GlobalFree (hDIB) ; 
DeleteDC (hMemDC) ; 
ReleaseDC ChWnd, hDC) ; 


break ; 
[Other program lines] 
CREATEDISCARDABLEBITMAP Win2.0 mWind0 eWin3.1 
Purpose Creates a DDB bitmap that is compatible with a device. Windows can discard the bitmap data if 
the bitmap is not selected. 
Syntax HBITMAP CreateDiscardableBitmap(HDC hDC, int nWidth, int nHeight); 
_ Description This function is identical to CreateCompatibleBitmap(), except that the memory for the bitmap 


is discardable. CreateDiscardableBitmap() creates a DDB bitmap with the same number of color 
panes and the same number of color bits per pixel as the device specified byhDC. The bitmap can 
then be selected into a memory device context and drawn upon. 

The bitmap memory area is not initialized when created. It will be filled with random bytes 
and can be converted to’a solid color by using a GDI function, such as Rectangle(), to paint the 
memory device context. VA, 

Windows will only discard the bitmap data if the bitmap i is not selected into a device context. 
The pape can test st whether the bitmap has been discarded by determining if SelectObjectQ) 
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Uses 


Returns 
See Also 


Parameters 
hDC 


| nWidth 
nHeight 


Example 
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returns NULL when an attempt is made to select the bitmap. In that case, the bitmap handle 
should be deleted with DeleteObject(), and the bitmap re-created and redrawn. 


Memory device contexts and compatible bitmaps allow an application to draw a complex figure in 
memory, and then quickly copy it to a physical device using BitBit() and similar functions. This 
technique can be more attractive than letting an image appear in sections on the screen. It is also 
an efficient way to draw small repeating patterns (see the following example). Having the 
memory for the bitmap discardable gives Windows the maximum freedom to use available 
memory. 


HBITMAP, the handle of the bitmap created. Returns NULL on error. 
CreateCompatibleDC(), CreateCompatibleBitmap() 


HDC: The device context handle for the physical device with which the bitmap is to be compat- 
ible. Typically, this is a handle to the window’s client area device context, retrieved by either 
GetDC() or BeginPaint(). 

int: The width, in pixels, to which the bitmap is to be initialized. 
int: The height, in pixels, to which the bitmap is to be initial- f 
ized. ee : 
This example draws nine identical patterns on the window’s 
client area when the user clicks the “Do It!” menu item. (See 
Figure 15-10.) Rather than use the GDI painting functions for 
each of the drawings, the application draws the pattern to a a 
memory device context containing a bitmap compatible with _ 4 
the screen. As soon as that pattern is painted to the memory 
device context, the pattern can be efficientiy copied to the 
window's client area using BitBit(). 

This code fragment tests to see if the discardable bitmap 
is still valid using SelectObject(). In this case, the bitmap is 
redrawn every time the “Do It!” menu item is selected. A more 
complex program would draw the bitmap in a separate func- Bas aeroremntnl 
tion. This function would be called at the beginning of the pro- Fipine 1 5-10. CreateDis- 


_ gram, and again later if the bitmap was discarded and needed cardableBitmap() Example. 


to be re-created and redrawn. 


lis FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG Param) 


static HBITMAP hBitmap ; 

HDC hDC, hMemDC ; 

int i, j; 

switch (iMessage) /* process windows messages */ 


case WM_CREATE: 
hDC = GetDC ChWnd) ; 
hBitmap = Gi eat es scardablebiemap Choc, 50, 50) ; 
Researene ChWnd, hdc) ; 
break ; 

case WM_ COMMAND: /* process menu items */ 
switch (wParam) 
{ . 


case IDM_DOIT: a he 21st create a memory de */ 
hDC = GetDC ChWnd) ; a 
hMemDC = crestecomeatiolebe ChDC) ; 
if (SelectObject (hMemDC, heitaap) & = NULL) 
{ . 
DeleteObject (hBitmap) ; 
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} 
return (OL) ; 


hBitmap = CreateDiscardableBitmap 
Choc, 50, 50) ; 

} 
/* paint on memory device context */ 
Rectangle ChMemDC, 0, 0, 50, 50) ; 
SelectObject (hMemDC, GetStockObject 

(BLACK_BRUSH)) ; 
Ellipse (hMemDC, 0, 0, 50, 50) ; 
SelectObject (hMemDC, GetStockObject 

(WHITE_BRUSH)) ; 
Rectangle (hMemDC, 5, 5, 45, 45) ; 
SelectObject (hMemDC, GetStockObject 

(BLACK_BRUSH)) ; 
Ellipse (hMembDc, 10, 10, 40, 40) ; 
SelectObject (hMemDC, GetStockObject 

CWHITE_BRUSH)) ; 
Rectangle (hMemDC, 15, 15, 35, 35) ; 

/* now copy the memory dc to screen */ 

for (j =O; j <3; j++) 
{ 


for C=O; 1<3 7 it+*) 
¢ 


BitBlt Choc, 50 * j, 50 * i, 
50 + (50 * jd), 
50 + (50.* i), hMempDC, 
0, 0, SRCCOPY) ; 
} 

} 

DeleteDC (hMemDC) ; 

ReleaseDC ChWnd, hDC) ; 


break ; 
case LDM_QUIT: /* send end oF application message */- 
DestroyWindow ChWnd). ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 


DeleteObject (hBitmap) ; 

PostQuitMessage (0) ; 

break ; ou 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


GeTBrrmaPBITs . wWin2.0 .mWin3.0 mWin3) 

Purpose Loads the DDB bitmap data into a memory block. 

Syntax DWORD GetBitmapBits(HBITMAP hBitmap, LONG dwCount, LPSTR lpBits); — 

Description DDB Bitmaps consist of a header of type BITMAP, and a block of data that contains the color data 
for each pixel in the bitmap. GetObject() is used to retrieve the data in the BITMAP header. 
GetBitmapBits() is used to retrieve the pixel data. The size of the memory block can be computed 
from the BITMAP data retrieved with GetObject. Use the formula 
dwCount = (DWORD) bm.bmWidthBytes * bm.bmHeight * bm.bmPlanes ; 

Uses . Used in cases where the application needs to selectively change some of the color pixels in the 
‘DDB bitmap. For example, a bitmap used as a button can be copied and modified to sreate a 
similar bitmap showing the button in a depressed or activated state. 

Returns DWORD, the number of bytes copied. Zero on error. 

See Also : SetBitmafBits(), GetObject() 

Parameters . 

hBitmap HANDLE: The handle of the bitmap. 


/ 


dwCount 
lpBits 


Example 
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DWORD: The number of bytes to copy to the IpBits buffer. Use the dwCount formula to compute 
this number. 


LPSTR: A pointer to a memory block to hold the bitmap data. Normally, this block is allocated 
using GlobalAlloc(). 


This example loads a bitmap from the application’s resource data when the WM_CREATE mes- 
sage is processed. The bitmap’s data is loaded into a temporary global memory block. Each byte of 
the bitmap data is examined. White pixels are converted to sii 
black, and black pixels to white. Colored pixels are not =" generic _ [~ [+ 
changed. The modified bitmap data is then written back to the . 
bitmap, and the global memory block freed. The bitmap is dis- ; 

played as a stretched image on the window's client area when 
the user clicks the “Do It!” menu item. Although not visible in 
Figure 15-11, the colors on the interior of the pen are not 
changed by the transformation. Note that this example as- 
sumes eight color bits per pixel. The program logic would need Figure 15-11. GetBitmap- 
to be expanded to cover other color resolutions. Bits() Example. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


static HBITMAP hBitmap ; 

HDC . hDC, hMemDC ; 

int nStrMode ; 

BITMAP bm ; 

DWORD dwBitmapSize, dwCount ; 

HANDLE hMem ; 

LPSTR ~- LpMem, LpData ; 

switch (iMessage) /* process windows messages */ 


case WM_CREATE: 
hBitmap = LoadBitmap (ghInstance , “pen") ; 
GetObject (hBitmap, sizeof (BITMAP), CLPSTR) &bm) ; 
dwBitmapSize = (DWORD) bm.bmWidthBytes * bm. bmHeight * 
a bm.bmPlanes ; 
hMem = GlobalAlloc (GMEM_MOVEABLE, dwBitmapSize) ; 
tpMem = GlobalLock ChMem) ; 
GetBitmapBits (hBitmap, dwBitmapSize, LpMem) ; 
ipData = lpMem ; 
for CdwCount = 0; ; dwCount < Cue i taapstee ; dwCount++) 


{ 
if (COxff.= =. (BYTE). *LpData): ; 
*lpData =0; /* chaivas white to black */ 
else if (0 == (BYTE) *LpData) 
*lpData = Oxff ; /* change black to white */ 
LpDatat+ ; ; ; ; 
} 


SetBitmapBits (hBitmap, dwBitmapSize, lpMem) ; 
GlobalUnlock ChMem) ; — 
GlobalFree ChMem) ; 
break ; 

case WM COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
hMemDC = CreateCompatibleDC C(hDC) ; 
SetStretchBltMcde (hDC, COLORONCOLOR) ; 
SelectObject (hMemDC, hBitmap) ; 
StretchBlt ChDC, 10, ‘10, 200, 80, hMemDC, 
0, 0, 60, 60, SRCCOPY) ; 
DeleteDC (hMemDC) ; 
ReleaseDC (hWnd, hDC) ; 
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break >; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 
} oe: 
break ; 
case WM_DESTROY: /*®* stop application */ 


DeleteObject ChBitmap) ; 
PostQuitMessage (0) ; 


break ; 
default:: ‘/* default windows message processing */ 
7 ; return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (COL) ; 

} 6 Se 

GrrBrrmaPDimEnston  mWin2.0) mWin3.0) Win3.l 

Purpose Retrieves two values that were associated with the bitmap by a previous call to SetBitmap- 
Dimension(). 

Syntax DWORD GetBitmapDimension(HBITMAP hBitmap); 

Description The SetBitmapDimension() function sets two integer values, X and Y, which are associated with 
the bitmap. These values do not affect the bitmap. They are provided so that an application can 
store dimensional data with the bitmap. This is preferable to using static or global variables to 
store the width\and height of the bitmap. The Windows SDK documentation suggests using the 
MM_LOMETRIC system of units (0.1 mm per unit) to specify the bitmap size. Because the values 
are not used in ainting the bitmap, any system of units (including device units — pixels) can 
be used. 

Uses Handy if an application uses a number of bitmaps that are different sizes. 

Returns DWORD. The low-order word contains the X value. The high- __ = 
order word contains the Y value. If SetBitmapDimension() Mm —~ © generic. eye . 

; not called previously to set these values, zero is returned. itl Quit — 
‘ a , 0 It! 

See Also SetBitmapDimension() a == 

Parameters 

hBitmap HBITMAP: The handle of the bitmap. . 

Example This example, which is illustrated in Figure 15-12, sets the “di- 


mension” values associated with the bitmap to 60,60 when the Bitmap X = 60, Y = bU 
bitmap is first loaded from the resource file. When the user : 
clicks the “Do It!” menu item, the bitmap is painted andthe Figure 15-12. GetBit- 


“dimension” values are displayed. - mapDimension() Example. 

long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG \Param) 
C é : , 

static HBITMAP hBitmap ; 

HDC hDC, hMemDC ; 

DWORD dwBmSize ; 

char cBuf £128] ; 

switch (iMessage) /* process windows messages */ 


case WM_CREATE: 
hBitmap = LoadBitmap (ghInstance , Pen ase 
pate ermaeptnens ten SRE NERO, 60, 60) ; 
break ; 
case WM_| COMMAND: = /* process menu .items */ 
switch (wParam) _ 
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} 
return (OL) ; 


} 


GetTDIBits 
Purpose 


Syntax 


Description 


Uses 


Returns 
See Also 


Parameters” 


RDC 


—-. Bitmap 


default: 
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case IDM_DOIT: /* User hit the "Do it” menu ives */ 
hDC = GetDC ChWnd) ; 
hMemDC = cheatecharsesblane ChdC) ; 
SelectObject (hMemDC, hBitmap) ; 
BitBlt Choc, 10, 10, 60, 60, hMemDC, 0, 0, 
SRCCOPY) ; 
DeleteDC ChMempc) : 
dwBmSize = GetBitmapDimension (hBitmap) ; 
TextOut ChDdC, 10, 80, cBuf, wsprintf (cBuf, 
“Bitmap X = 2d, Y= ad", LOWORD (dwBmSize), 
HIWORD CduBmSized)) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: /* send end of application message / 
.DestroyWindow Chwnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: ‘ 
DeleteObject (hBitmap) ; 
PostQuitMessage (0) ; 
break ; 


/* stop application */ 


/* default windows message processing. ad 
return DefWindowProc shod: iMessage, wParam, LParam) ; 


OWin2.0 mWin30 mWin3l 


Fills in the BITMAPINFO data for a device-independent bitmap, and/or writes a DIB’s pixel data 
into a memory buffer. 


int GetDIBits(HDC ADC, HANDLE hBitmap, WORD nStartScan, WORD ea LPSTR 
lpBits, LPBITMAPINFO [pBitsInfo, WORD wlsage); 


This function does two related functions. If the /pBits parameter is NULL, GetDIBits() fills in the 
BITMAPINFO data structure to which the [pBitsInfo parameter points. This is the normal way to 
copy device context color values to the bmiColors part of the BITMAPINFO data structure. 

If LpBits is not NULL, the function copies the pixel values for a bitmap to the memory area 
pointed to by /pBits. In this case, /pBits normally points to an address in a global memory block, 
right after the BITMAPINFO header data. A memory block containing a combination of a 


- BITMAPINFO header, followed by the bitmap bits, is a complete device-independent bitmap. If 


the bitmap is to be written to a disk file, the data just described should be preceded by a 
BITMAPFILEHEADER data structure. Note that the origin for DIBs is the bottom left corner of 
the array instead of the top left corner. This origin makes the bits upside down relative to the 
default MM_TEXT mapping mode for a device context. 


Used in the creation of device- independent bitmaps. For large bitmaps, the bitmap data can be 
read as a Series of horizontal bands by specifying different nStartScan and nNumScans values. 
This technique reduces memory demands. 


int, the number of lines of pixels copied from the bitmap. Zero 01 on error.. 


SetDIBits(), SetDIBitsToDevice(), StretchDIBits(). The function description for Create- 
piphnene includes the BITMAPINFO venee definition. See ne ses 


\ 


HDC: The device context handle for the device to which the DIB isto be iaed: The device 


context will determine the color values written to the. RGBQUAD color table in the BITMAPINFO 


‘Structure. 


HBITMAP: A handle to the bitmap. 
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nStartScan 
nNumScans 


IpBits 


24 


_- WORD: The first pixel line number on which to start in the bitmap. Usually, zero. 


WORD: The number of lines of pixels to ne ihe Ponmally, equal to the vertical height of the 
bitmap in pixels. 


LPSTR: A pointer to a memory buffer that will contain the bitmap data after the function is 
called. If set to NULL, only the /pBits/nfo data is written, not the bitmap bits. Setting this param- — 
eter to NULL is the normal way to write a set of color values to the bmiColors data section of the 
BITMAPINFO structure. The number of colors written will depend on the color resolution of the 
device. (See Table 15-5.) - . 


A fonpeirene bi unde, bmiColors will contain two entries. Each bit in the sine data will beset one 
pixel. 


A bitmap with 16 colors. bmiColors will contain 16 entries. Each pixel requires four bits of information in the — 
bitmap data. The four bits represent an index in the color table. . 


. Abitmap with 256 colors. ‘bmiColors. will contain 256 entries. Each pixel requires a byte of information in the 
". bitmap data. The byte value represents an index into the color table. - 


A bitmap with 224 colors. bmiColors will contain NULL. Each pixel requires three bytes of information, 
representing the RGB (Red, Green, Blue) color bytes. 


Table 15- 3. Color Resolutions. 


IpBitsInfo LPBITMAPINFO: A pointer toa ‘BITMAPINFO data structure that specifies the size and color 
_ format of the bitmap. The pointer can point to the top of the same memery area the bitmap data 
-is being written to if the BITMAPINFO data has been initialized. 
wUsage WORD: Specifies whether the bmiColors/ ] fields at the end of the BITMAPINFO data structure 
ae tae , contain explicit RGB. color values, or if they are indexes into the currently realized logical pal- 
-- ette. ‘wUsage can be either DIB_ PAL COLORS for palee colors; 0 or DIB_RGB_COLORS for ex- 
ea plicit RGB colors. ° 
Example | Loire The example under CisatabipPatternBrash( inci both usages of this function. 
GeTSTRETCHBLTMoDE. =. —ss—‘<‘CS;~;:SCw”C~™”~C*«ia Win Win 8.0 Win 3 
' Purpose. : Determines the current bitmap stretching mode of a device context. 
Syntax “int GetStretchBitMode(HDC hDC); 
Description The stretching mode determines how pixels are eliminated if a bitmap i image is changed in size. ° 
Bitmaps that are increased i in size end up simply adding more matching pixels between existing 
~ ones. The stretching mode becomes a property of the device context, and remains in effect until 
the device context is deleted or a new stretching mode is set. . 
Uses Used to determine if the stretching mode needs to be changed using SetStretchBitMode(). 
Returns | Returns the current stretching mode which can be any ot the modes listed i in Table 15-6. 


BLACKONWHITE 
COLORONCOLOR - 
WHITEONBLACK 


pesavest black repel at the expense of White 0 ones. 
. Deletes eliminated lines. No attempt to use the color. value sivawien 2 the eliminated pixels. 
Preserves white pixels at the expense of black ones. 


Table 15-6. Bitmap Stretching Modes. 
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See Also” 


Parameters 
ADC 


Example 


LoaApBITMAP 


Purpose 
Syntax 
Description 


Uses 
Returns 


See Also 


Parameters 
hInstance 


[pBitmapName 


Example 
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SetStretchBltMode(), StretchBit() 


HDC: The device context handle. 
See the example under StretchBit(). 


mWin2.0 mWin30 mWin3.1 
Loads a bitmap resource into memory. 


HBITMAP LoadBitmap(HANDLE hJnstance, LPSTR ipBitmapName); 


Bitmap images are normally created using the Windows SDKPaint application. The output of 
SDKPaint is stored in a file with the BMP extensicn. To use a bitmap, the application must list 
the bitmap file in the .RC resource script file, using the BITMAP statement. Within the 
application’s code, LoadBitmap() is used to load the bitmap data from the resource data into 
memory. After the application is finished using the bitmap, DeleteObject() should be called to 
free the bitmap from memory. 

This function will load either DDB or DIB bitmaps. If a DIB is loaded, it will be converted to 


a DDB, losing color information. See the discussion on DIBs at the beginning of this chapter for 


an example using the DIB color data to create a logical palette. 
This is the first step in using a bitmap file within a program. 


HBITMAP, the bitmap handle. Returns NULL on error, usually ineanittg that the bitmap was not 
found in the resource data. 


DeleteObject(), PatBlt() 


HANDLE: The instance handle of the module (running pro- 
gram) which has the bitmap in its resource data. You can use 
GetWindowWord() to obtain this value. If hJnstance is NULL, : 
LoadBitmap() accesses one of the predefined bitmaps listed 
below. 


LPSTR: A pointer to a null-terminated character string con- a 
taining the bitmap name. The string is the name to the left of Figure 15-13. LoadBitmap() 
the BITMAP statement in the application’s .RC resource script and PatBlt() Example. 

file. For example, the line - 


mybitmap BITHAP bitfile.bmp 


names the bitmap “mybitmap.” The bitmap data is loaded from the file BITFILE.BMP. 
IfhInstance is NULL, [pBitmapName must be one of the following predefined bitmap names: 


‘OBM_BTNCORNERS, OBM_BTSIZE, OBM_CHECK, OBM_CHECKBOXES, OBM_CLOSE, 


OBM_COMBO, OBM_DNARROW, OBM_DNARROWD, OBM_DNARROWI, OBM_LFARROW, 


-OBM_LFARROWI, OBM_MNARROW, OBM_OLD_CLOSE, OBM_OLD_DNARROW, 


OBM_OLD_LFARROW, OBM_OLD_REDUCE, OBM_OLD_RESTORE, OBM_OLD_RGARROW, 
OBM_OLD_UPARROW, OBM_OLD_ZOOM, OBM_REDUCE, OBM_REDUCED, OBM_RESTORE, 
OBM_RESTORED, OBM_RGARROW, OBM_RGARROWD, OBM_RGARROWI, OBM_SIZE, 
OBM_UPARROW, OBM_UPARROWD, OBM_UPARROWI, OBM_ZOOM, OBM_ZOOMD 


The values starting with OBM_ OLD are eae used by versions of Windows prior to 3.0 | 


This example paints the client area with a bitmap ster brush, as nied in Figure 15-13. The 
client area pattern colors are inverted when the user clicks the “Do It!” menu item. 
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The program’s resource file includes a BITMAP statement to load a bitmap file from disk, and 
add it to the program’s resources. The bitmap file BRUSHPAT.BMP is an 8 by 8 pixel bitmap 
created with the Windows SDKPaint areaon: . 


o> GENERIC. RC 


/* generic.rc */ 


#include <windows.h> 
Hinclude “generic.h" 


generic ICON generic.ico 
brushpat BITMAP brushpat.bmp 
generic — MENU 
BEGIN , ; : : 
MENUITEM "&Do It!" . IDM_DOIT 
MENUITEM "“&Quit", IDM_QUIT 
END 8 


The bitmap is loaded into memory when the WM_CREATE message is processed. The client area 
size is kept current by processing WM_SIZE messages. Because PatBlt() paints using the cur- 
rently selected brush, the bitmap is used to create a pattern brush using CreatePatternBrush(). ' 
PatBlt() paints the entire client area with the bitmap pattern brush every time a WM _PAINT 
message is received. 

PatBit() is also called when the user clicks the “Do It!” menu item. In this case, the 
DSTINVERT raster code is specified, inverting the colors of the client area. Clicking the “Do It!” 
menu item a second time restores the pattern colors to their original state. 


© GENERIC.C WndProc() Function 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HBRUSH | hBrush, hOldBrush ; 

static — HBITMAP hBitmap ; 

static int nXclient, nYclient ; 

PAINTSTRUCT ps; 

HDC hdc ; 

switch (CiMessage) /* process windows messages */ 


case WM_CREATE: ; 
hBitmap = LoadBitmap (ghInstance , "“brushpat") ; 


break ; 

case WM_SIZE: 
nXclient = LOWORD (lParam) ; /* get client size */ 
nY¥client = HIWORD (lParam) ; - 
break ; 


case WM_PAINT: a 
BeginPaint (hWnd, &ps) ; 
hBrush = CreatePatternBrush (hBitmap) a 
hOtdBrush = SelectObject (hDC,.hBrush) ; 
PatBlt (ps.hdc, 0, 0, nXclient, nveltent, 

PATCOPY) ; 4 

SelectObject (ps. hde, AOLdBrush) ; 
DeleteObject (hBrush) ; 
EndPaint (hWnd, &ps) ; 
break ; ; 

case WM_COMMAND: /* process menu items */ 
switch (wParam) 
£ 


case IDM_ DOIT: /* User hit the “Do it” menu item */ 


hDC = GetDC ChWnd) ; 
PatBlt Choc, 0, Q, aXelient, nY¥client, 
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} 


DSTINVERT) ; 
ReleaseDC ChWnd, hDC) ; 
break ; 
case IDM_QUIT:~—- /* send end of application message */ 
DestroyWindow (hWnd) ; - 
break ; 
} . 
break ; 
case WM_DESTROY: 
DeleteObject (hBitmap) ; 
PostQuitMessage (0) ; 
break ; 
default: 


/* stop application */ 


/* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


PaTtBLtT 
Purpose 
Syntax 
Description 


Uses 
Returns 
See Also 


Parameters 
hDC 


PATCOPY 
PATINVERT 
DSTINVERT 
BLACKNESS 
WHITENESS 


eWin20 mWin30 mWin3l 
Outputs a pattern brush to a device. 

BOOL PatBIt(HDC hDC, int. X, int Y, int nWidth, int nHeight, DWORD dwRop); . 

The currently selected brush is output to the device referenced by ADC: The brush is used to fill 
the rectangle defined by the X, Y, nWidth, and nHeight parameters. The brush is combined with 
the background colors in different ways, depending on the raster-operation code specified in 


dwRop. 

Used to fill regions with a pattern. . 
BOOL. Nonzero if the function was successful, zero on error. 
BitBlt(), CreatePatternBrush(), LoadBitmap() 


HDC: The destination device context handle. 


int: The logical X coordinate of the upper left corner of the rectangle that is to be filled with the 
selected brush. 


The logical Y coordinate of the upper left corner of the rectangle that is to be filled with the 
selected brush. 


int: The width, in logical units, of the rectangle that is to be filled with the selected brush. 
int: The height, in logical units, of the rectangle that is to be filled with the selected brush. 


DWORD: One of the raster-operation codes in Table 15-7. These codes determine how the colors 
of the brush are combined with the existing colors of the background. 


Solis: Recon a ee 
Copies the pattern to the destination. 
Combines the destination bitmap with the pattern using the Boolean OR operator. 
Inverts the destination bitmap. 

Tums all output black. . 

Tums all output white. This is a quick way to blank a device context. 


Table 15-7. Raster-Operation Codes that PatBli() Can Use. 


Example . 


See the previous example under LoadBitmap(). - 
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SETBITMAPBITS | aWin2.0 wmWin30 wWin3l 


Purpose Sets the pixel data for a DDB bitmap. 
Syntax LONG SetBitmapBits(HBITMAP hBitmap, DWORD dwCount, LPSTR lpBits); 
Description Normally, the pixel bit data array is set when CreateBitmap() i is called. SerblonapBits0 a allows 
the pixel data to be set or changed later. 
Uses Generally, used if the application modifies the pixel data before displaying it. 
Returns LONG, the number of bytes used in setting the bitmap bits. Zero on error. 
See Also CreateBitmap(), CreateBitmapIndirect() ; 
Parameters 
hBitmap HBITMAP: The handle of the bitmap which will receive the color bit data. 
dwCount DWORD: The number of bytes of data in the array pointed to by  ;RagIreannst 
[pBits. 
lpBits LPSTR: A pointer to an array of bytes containing the color bit 
data. The array should be at least dwCount bytes in size. 
This example (see Figure 15-14) paints a small bitmap con- | 


Example 


taining an “H” at location 10,10 in the upper left corner ofthe 
window’s client area when the user clicks the “Do It!” menu Figure 15-14. SetBitmap- 
item... ae Bits() Example. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


static 
HDC 
static 


switch (iMessage) 
{ 


HBITMAP hBitmap ; 

hdC, hMemDC ; 

BYTE BitMapBits [48] = /* define bitmap pattern */ 
0x00, 0x00, 0x00, 0x00, 

0x00, 0x00, 0x00, 0x00, 

Ox0f, Oxff, Oxff, Oxf0, 

OxOf, Ox7f, Oxfe,.Oxf0, 

OxOf, Ox7f, Oxfe, OxfO0, 


OxOf, Ox7f, Oxfe, Oxf0, 


OxOf, 0x00, 0x00, Oxf0, 
OxOf, Ox7f, Oxfe, Oxf0, 
OxOf, Ox7f, Oxfe, Oxf0, 
OxOf, Oxff, Oxff, OxfQ, 
0x00, 0x00, 0x00, 0x00, 


_. 0x00, 0x00, 0x00, 0x00 } ; 


/* process windows messages */ 


case WM_CREATE: 
hBitmap = CreateBitmap (32, 12, 1, 1, NULL) ; 
SetBitmapBits (hBitmap, 48, 
CLPSTR) BitMapBits) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
case TDM_ DOIT: /* User hit the “Do it" menu item */ 
hDC = GetDC (hWnd) ; 
hMemDC = CreateCompatibleDC C(hDC) ; 
SelectObject (hMemDC, hBitmap) ; 
‘BitBlt (hdc, :10, 10, 32, 12, hMemDC, 0, 0, 
SRCCOPY) ; : 
DeleteDC ChMemDC) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: . 4* pene end of application message */ 
Dest teva ndon (hWnd) ; 
break ; 
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} 
break ; 
case WM_DESTROY: 
DeleteObject (hBitmap) ; 
PostQuitMessage (0) ; 


/* stop application */ 


b k ; : 
default: ave /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
} 
SETBITMAPDIMENSION mWin20 mWin3.0 mWin3.l 
Purpose Sets two values that are associated with the bitmap. These values can be retrieved later using 
GetBitmapDimension(). 
Syntax: LONG SetBitmapDimension(HBITMAP hBitmap, int.X, int Y); 
Description The SetBitmapDimension() function sets two integer values, X and Y, which are associated with 
. the bitmap. These values do not affect the bitmap. They are provided so that an application can 
store dimensional data with the bitmap. This is preferable to using static or global variables to 
store the width and height of the bitmap. The Windows SDK documentation suggests using the 
MM_LOMETRIC system of units (0.1 mm per unit) to specify the bitmap size. Because the values 
are not used in painting the bitmap, any system of units (including device units—pixels) can be 
used. 
Uses Handy if an application uses a number of bitmaps that are different sizes. 
Returns DWORD, the previous bitmap dimensions. The low-order word contains the X value. The high- 
' order word contains the Y value. If SetBitmapDimension() was not called previously to set these 
values, zero is returned. 
See Also GetBitmapDimension() 
Parameters 
hBitmap HBITMAP: The handle of the bitmap. 
X int: The X value to associate with the bitmap. 
Y int: The Y value to associate with the bitmap. 
Example See the example under GetBitmapDimension(). 
SeTDIBirs OWin2.0 mWin3.0 mWin3.1 
Purpose Sets device-independent bitmap (DIB) pixel data to the data in a memory buffer. 
Syntax _ int SetDIBits(HDC 2DC, HANDLE hBitmap, WORD nStartScan, WORD ala cae LPSTR 
lpBits, LPBITMAPINFO [pBitsInfo, WORD wUsage); 
Description DIBs consist of header information followed by the bitmap data for each pial of the bitmap (see 
CreateDIBitmap() for descriptions of the header format). SetDiBits() allows an aeneaeon to 
modify the pixel data of the bitmap, changing the image represented. ° 
The bitmap must not be selected into a device context at the time SetDIBits() is called. For 
large bitmaps, the image can be changed in horizontal segments to minimize memory use. Specify 
a series of nStaritScan and nNumScans values to process bands of the bitmap data. 
Uses: Used when the application modifies the pixel data for the DIB bitmap prior to displaying it. One 
possible use is to change the colors of a button to show selection status. 
Returns int, the number of scan lines changed. Zero on error. 
See Also . CreateDIBitmap(), GetDIBits() — 
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Parameters a 

hDC ~ HDC: The device context handle. 

hBitmap HBITMAP: A handle to the bitmap. This value is returned by CreateDIBitmap(). 

nStartScan WORD: The first pixel line number on which to start in the bitmap. Usually zero, unless the 
bitmap is being set by several SetDIBits() calls, for horizontal bands of the bitmap image. 

nNumScans WORD: The number of lines of pixels to be copied. Normally, equal to the vertical height of the 
bitmap in pixels, unless the changes are being made one horizontal band at a time. 

lpBits . LPSTR: A pointer to a memory buffer that contains the bitmap data. 


lpBitsInfo _ LPBITMAPINFO: A pointer to a BITMAPINFO data structure that specifies the size and color 
format of the bitmap. The pointer can point to the top of the same memory area the bitmap data 
is being written to if the BITMAPINFO data has been initialized. 


: wUsage WORD: Specifies whether the bmiColors// fields at the end of the BITMAPINFO data structure 
contain explicit RGB color values, or if they are indexes into the currently realized logical pal- 
ette. wUsage can be either DIB_PAL COLORS for palette colors, or DIB_RGB_COLORS for ex- 


plicit RGB colors. 
oar generic| + [+ 


Example This example paints a Device-Independent Bitmap (DIB) on 
Dolt! Quit 


the window's client area. (See Figure 15-15.) Initially, the 
bitmap is colored black and white. When the user clicks the 
“Do It!” menu item, the bitmap data is altered so that any two 
black pixels next to each other (0 value for a byte within a 16- 
color. bitmap) are changed to a blue-black pixel combination. 
For simplicity, this example assumes a 16-color bitmap. 
Sixteen-color bitmaps use four bits per pixel in the bitmap 
. data, so each byte of data encodes two pixels. This example Figure 15. 15. Sait ) 
also omits error checking on memory allocation. Example. 
#define ALIGNLONG(i) CC i43)/4*4) 
#define WIDTH 


Hdefine HEIGHT 50 
#define COLORBITS 4 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ : : 


PAINTSTRUCT ps 7. 

static BITMAPINFOHEADER — Bi; 
LPBITMAPINFOHEADER lpbi ; 
static HBITMAP hBitmap ; 

HDC . hDC, hMemDC ; 

static HANDLE hDIB ; 

HBRUSH hdIBrush ; 

LPSTR ioeteiemses tpstTemp ; 
int : i, nBytes ; 

switch (iMessage) _/* process windows messages */ 


case WM_CREATE: 
hDC = GetDC ChWnd) ; 

/* ini Halize BITMAPINFOHEADER data */ 
Bi.biSize = sizeof (BITMAPINFOHEADER) ; ; 
Bi.biWidth = WIDTH ; ~ - (* B by 8 bitwap */ 
Bi.biHeight = HEIGHT; R 7 
Bi.biPlanes = 1; 

Bi.biBitCount = COLORBITS ; /* 16 colors */ 
Bi.biCompression = BI_RGB ; 
Bi-biSizeImage = CALIGNLONG ¢CWIDTH * COLORBITS)/8) 

* HEIGHT); 

Bi .bixPelsPerMeter =O; 
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Bi.biYPelsPerMeter = 0 ; 
Bi.biClrUsed = 0; 
‘Bi. biClrimportant = O;° 

/* create uninitialized DIB bitmap */ 
hBitmap = CeeatetESi tap ChDC, &Bi, OL, NULL, 

NULL, O) ; 

/* allocate memory for BITMAPINFO structure */ 
hDIB = GlobalAlloc (GHND, sizeof (BITMAPINFOHEADER) + 

16 * sizeof (RGBQUAD) + ; 

CALIGNLONGC(CWIDTH * COLORBITS)/8) * HEIGHT)); 
Lpbi = (BITMAPINFOHEADER FAR *) GlobalLock ChDIB) ; 

/*®* tricky way to copy Bi to top of BITMAPINFO */ 
*lpbi = Bi ; 

/* use GetDIBits() to initialize structure data */ 
GetDIBits ChDC, hBitmap, 0, 50, NULL, 

CLPBITMAPINFO) Lpbi, DIB_RGB_COLORS) ; 

/* create memory device context */ 
hMemDC = CreateCompatibleDC ChDC) ; 

/* select DIB bitmap into device context */ 
SelectObject (hMemDC, hBitmap) ; 

/* paint on memory device context */ 
SelectObject (hMemDC, GetStockObject (BLACK_ BRUSH)) - 
Rectangle (hMemDC, 0, 0, WIDTH, HEIGHT) ; 
SelectObject (hMemDC, GetStockObject (WHITE_BRUSH)) - 
Ellipse (hMemdC, 0,|0, WIDTH, HEIGHT) ; 

MoveTo (hMemDC, 0, 0) ; 
LineTo (hMemDC, WIDTH / 2, HEIGHT / 2) ; 
LineTo (hMemDC, WIDTH, 0) ; 

/* set pointer. to bitmap's bit data */ 
LpstBitmap = (LPSTR) Lpbi + 

(WORD). sizeof (BITMAPINFOHEADER) + 

(16 * sizeof CRGBQUAD)) ; 

GetDIBits (hDC, hBitmap, 0, HEIGHT, LpstBitmap, 

CLPBITMAPINFO) Lpbi, DIB_RGB_COLORS) ; 
GlobalUntock SHOE? 7 
DeleteDC (hMemDC) ; 

ReleaseDC Chiind, hbo) ; 
break ; 
case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
hMemDC = CreateCompat ibleDc (ps. hde) ; 
SelectObject (hMemDC, hBitmap) ; 
BitBlt (ps.hdc, 0, 0, WIDTH, HEIGHT, hMemDC, O, 
0, SRCCOPY) ; 
DeleteDC ChMemDC) ; 
EndPaint ChWnd, &ps) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch CwParam) 
{ 
case IDM_DOIT: 
hDC = GetDC ChWnd) ; 
lpbi = (BITMAPINFOHEADER FAR *) 
GlobalLlock ChDIB) ; 
LpstBitmap = (LPSTR) Lpbi.+ . ; 
CWORD) sizeof SOUT HOPI NE OUERUEN? i‘ 
(16 * sizeof CRGBQUAD)) ; 
nBytes = ALIGNLONG( (WIDTH * COLORBITS)/8) 
* HEIGHT ; 
LpstTemp = LpstBitmap ie 
ee fal change O bytes to 0x2C in bitmap data */ 
for (i = 0; i < nBytes ; i++) 


{ 
if (0 == *lpstTemp) /* if black * 
*lLpstTemp = Ox2c ; 
LpstTemp++ 7 
} 


SetDIBits (hDC, hBitmap, 0, HEIGHT, LpstBitmap, | 
(LPBITMAPINFO) Lpbi, DIB_RGB_COLORS) ; 
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- default: 


ReleaseDC (hWnd, BDC) 3 
GlobalUnlock ChDIB) ; 
InvalidateRect chund, NULL, TRUE) ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
'. break ; 


/* paint */ 


} 
break ; . 
case WM_DESTROY: . /* stop application */ 
GlobalFree ChDIB) ; 
PostQuitMessage (0) ; 
break ; a 
/* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return (QOL) ; 


} 

SeTDIBrtsToDEVICE OWin2.0 eWin3.0 mWin31 

Purpose Paints from a device-independent bitmap (DIB) directly to a device context. 

Syntax WORD SetDIBitsToDevice(HDC hDC, WORD DestX, WORD DestY, WORD nWidth, WORD 
nHeight, WORD SrcX, WORD SrcY, WORD nStartScan, WORD nNumScans, LPSTR lpBits, 
‘LPBITMAPINFO [pBitsInfo, WORD wUsage) ; 

Description This is the fastest method of painting a DIB to a device, once the DIB is stored in a memory buffer. 

Normally, the BITMAPINFO data pointed to by pBitsInfo will be right in front of the bitmap pixel 
data (pointed to by /pBits), all in the same memory block. 

Unless the BITMAPINFO color data is separately processed to realize a logical palette, the 
color data will be lost when the DIB is output to the device context. For example, a 256-color 
bitmap will be mapped to the 20 default system colors when output to a VGA device. Note that the 
origin for the DIB pixel data is the bottom left corner. The data is upside down relative to the 
default MM_TEXT mapping mode. 

Uses Outputs a DIB directly to the screen. Parts of a DIB can be output by manipulating the SrcX, 
SrcY, nStartScan, and nNumScans parameters. Memory demands for painting the DIB can be 
reduced by successively painting horizontal bands out of a DIB bitmap, rather than painting all of 
the image at once. 

You can also use a DIB as an alternative to direct manipulation of the screen pixels with the 
slow GetPixel() and SetPixel() functions. The changes can be made to the DIB data, and then 
periodically sent to the screen with SetDIBitsToDevice(). 

Returns WORD, the number of scan lines copied to the output device context. Zero on error. 

See Also CreateDIBitmap(), GetDIBits(), SetDIBits(), StretchDIBits() ~ 

Parameters 

hDC HDC: The device context on which the DIB will be output. 

DestX WORD: The logical X coordinate on the device context to start the bitmap output. 

DestY WORD: The logical Y coordinate on the device context to start the bitmap output. 

nWidth WORD: The width, in pixels, of the DIB. 

nHeight WORD: The height, in pixels, of the DIB. 

SrcxX WORD: The X position in the DIB from which to start reading pixel data for output. Normally 0. 

SreY WORD: The Y position in the DIB from which to start reading pixel data for output. Normally 0. 

nStartScan WORD: The line number of the horizontal line of pixels in the DIB that is the first line in the 


lpBits memory buffer. 
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WORD: The number of scan lines of the DIB that are contained in the memory buffer pointed to 


nNumScans 
by [pBits. . 
lpBits LPSTR: A pointer to the memory buffer that contains the pixel data. Normally, this follows the 
BITMAPINFO header data in a memory buffer. The pixel data can be in a separate buffer. 
lpBitsInfo LPBITMAPINFO: A pointer to an initialized BITMAPINFO data structure. This data describes 
the size and color data for the bitmap. See CreateDIBitmap() for a description of this data struc- 
ture. : 
wUsage WORD: Specifies whether the bmiColors/] fields at the end of the BITMAPINFO data structure 
contain explicit RGB color values, or if they are indexes into the currently realized logical pal- 
ette. wWsage can be either DIB_PAL_COLORS for palette col- 
ors, or DIB_RGB_COLORS for explicit RGB colors. | .__ Generic | ; = 2 : 
Caution This function cannot be used to output to a memory device con- anes oy ame 
‘ee aor e. Dolt! Quit 
Example The DIB example at the beginning of this chapter shows how SiR . 
_ to preserve the color data associated with a DIB by using it to 
realize a logical palette. This example paints a colored DIB 
bitmap and saves the bytes in a global memory buffer. The 
bitmap is painted to the screen when WM_PAINT messages Figure 15-16. SetDIBits- 
are received using SetDIBitsToDevice(). (See Figure 15-16.)  ToDevice() Example. 
#define ALIGNLONG(i> CCi#3 2/44), | 
H#define WIDTH 150 
#define HEIGHT 50 
#define COLORBITS 4 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . é 


PAINTSTRUCT ps; 

static BITMAPINFOHEADER bi ; 
LPBITMAPINFOHEADER Lpbi ; 

LPBITMAPINFO ‘lpBitinfo ; 

static HBITMAP hBitmap ; 

HDC hDC, hMemDC ; 

static HANDLE hDIB ; 

HBRUSH hBrush ; 

LPSTR LpstBitmap, LpstTemp ; 
int i, nBytes ; . 
switch (iMessage) /* process windows messages */ 
{ ‘ ; 


case WM_CREATE: 
hDOC = GetDC ChWnd) ; 
/* initialize BITMAPINFOHEADER data */ 
bi.biSize = sizeof (BITMAPINFOHEADER) ; 
bi.biWidth = WIDTH ; /* 8 by 8 bitmap */ 
bi.biHeight = HEIGHT ; 
bi.biPlanes =1; . 
bi.biBitCount = COLORBITS ; /* 16 colors */ 
bi.biCompression = BI_RGB ; 
bi.biSizeIlmage = CALIGNLONG(CWIDTH * COLORBITS)/8) 
* HEIGHT); ae 
bi.bixPelsPerMeter 
bi.biYPelsPerMeter 
bi.biClrUsed = 0 ; 
bi.biClrimportant =0 ; 
/* create uninitialized DIB bitmap */ 
hBitmap = CreateDIBitmap ChDC, &bi, OL, NULL, 
" "NULL, 0) > 
, | 7* allocate memory for BITMAPINFO structure */ 
hDIB = GlobalAlloc (GHND, sizeof (BITMAPINFOHEADER) +: 


0 
0 


oot 
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16 * sizeof (RGBQUAD) + 

CALIGNLONGC(CWIDTH * COLORBITS)/8) * BELGHT 293 
Lpbi = (BITMAPINFOHEADER FAR *) GlobalLock ChDIB) ; 

/* tricky way to copy bi to top of BITMAPINFO */ 
*lpbi = bi ; 

/* use GetDIBits() to init lpbi struct data */ 
GetDIBits (hDC, hBitmap, 0, 50, NULL, 

CLPBITMAPINFO) Lpbi, DIB_RGB_COLORS) ; 


/* create memory device context */ 
hMemDC = CreateCompatibleDC ChDC) ; 

/* select DIB bitmap into device context */ 
SelectObject (hMemDC, hBitmap) ; 

/* paint on memory device context */ 
hBrush = CreateSolidBrush (RGB (255, 80, 80)) ; 
SelectObject (hMemDC, hBrush) ; 

Rectangle (hMemDC, 0, 0, WIDTH, HEIGHT) ; 
DeleteObject (SelectObject (hMemDC, 

GetStockObject (WHITE_ BRUSH))) ; 
Ellipse ChMempC, 0, 0, WIDTH, HEIGHT) ; 
hBrush = CreateSol idBrush (RGB 0, 0, 255)) ; 
SelectObject (hMemDC, hBrush) ; 

Ellipse. ChMemDC, “WIDTH te 3, 0, 2 * WIDTH / 3, 
oO HEIGHT) ; 
DeleteObject Ceelaceobiece Chiembe, 

GetStockObject (BLACK_BRUSH))) ;. 
Ellipse ChMemDC, 2 * WIDTH / 5, HEIGHT / 5, 

3 * WIOTH / 5, 

4 * HEIGHT /.5) ; 

/* set pointer to bitmap's bit data hd 
LpstBitmap = (LPSTR) Lpbi + 

CWORD) sizeof (BITMAPINFOHEADER) + 

(16 * sizeof (RGBQUAD)) ; 

_GetDIBits ChDC, hBitmap, 0, HEIGHT, LpstBitmap, 

(LPBITMAPINFO) lpbi, DIB_RGB_COLORS) ; 
GlobalUnlock (hDIB) ; 

DeleteDC ChMemDC) ; 

Heteagenc ChWnd, hDC) ; 

break ; 

“case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
LpBitInfo = (LPBITMAPINFO) GlobalLock ChDIB) ; 
lpstBitmap = (LPSTR) LpBitInfo +. 
- - (WORD) sizeof (BITMAPINFOHEADER) + - 
“(16% sizeof (RGBQUAD)) ; 

SetDIBitsToDevice (ps.hdc, 10, 10, WIDTH, HEIGHT, - 
0, 0, 0, HEIGHT, LpstBitmap, ipBitinfo, 
DIB_RGB_COLORS) ; 

GlobalUnlock (hDIB) ; 

EndPaint ChWnd, &ps) ; 

break ; 


[Other program lines] aan 4 


SETSTRETCHBLTMODE mWin20 mWin3.0 .mWin3.1 
Purpose Sets the bitmap stretching mode for the StretchBit() function... 
Syntax int SetStretchBltMode(HDC hDC, int nStretchMode); 


Description The stretching mode determines how pixels are eliminated if a bitmap image is reduced in size. | 
Bitmaps that are increased in size simply add more matching pixels between existing ones. The 
" stretching ‘mode becomes a property of the device context, and remains in effect until the device 
context is deleted ora new stretching mode is set. 


Uses The most’ desirable stretchi ; mode will depend on the bitmap being reduced. —_ withafew =. 


thin lines will be processed ost effectively by BLACKONWHITE. Images with a few fat lines will be. 
processed more effectively by TON CE General color i images can use COLORONCOLOR. 
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Returns int, the previous stretching mode. 

See Also GetStretchBltMode(), StretchBlt() 

Parameters 

hDC HDC: The device context handle that will have the stretching mode set. 


nStretchMode int: One of the values defined in WINDOWS.H and listed in Table 15-8. 


BLACKONWHITE Preserves black pixels at the expense of white ones. 


COLORCNCOLOR Deletes eliminated lines. No attempt to use the color value information of the eliminated pixels. 
WHITEONBLACK Preserves white pixels at the expense of black ones. — 


Table 15-8. Bitmap Stretching Modes. 


Example See the following example under the StretchBIt() function description. 

STRETCHBLT | ; mw Win20 =m Win30 ). mWin3l 

‘Purpose Copies a bitmap jo one device context to another, stretching or Ponteesne thei uuase to fit the 
destination rectangle. 

Syntax BOOL StretchBIt(HDC hDestDC, int X, int Y, int nWiath, int nHeight, HDC hSrcDC, int XSre, int 
YSre, int nSrcWidth, int nSrcHerght, DWORD dwRop); 

Description This function is similar to BitBlt(), except that it has the added ability to stretch or compress the 


bitmap. The method used to fill in missing pixels (if enlarging), or delete overlapping pixels (if 
shrinking), is governed by the current stretching mode of the device context. 
SetStretchBltMode() sets the stretching mode. 
The image can be inverted, or made a mirror image, by changing the signs of either the 
source or destination bitmap size. If StretchBlt() copies a monochrome bitmap to a color device 
- context, white bits (1) are set to the background color, and black bits (0) are set to the fore- 
ground color. 


Uses : Allows a bitmap to be sized. This function is convenient for windows that are sizeable, but may 
need to enlarge or contract bitmap images depending on the size of the window. The tool bars on 
' the left of the Windows Paintbrush application are an excellent example of scaling graphics im- 
ages to fit the window size. Large expansions of bitmaps will result in jagged edges. Consider 
using a metafile for large images. 


Returns BOOL. Nonzero if the bitmap was drawn, zero on error. 
_ See Also SetStretchBltMode(), GetDeviceCaps() to check whether the device supports raster operations. 
Use the RC_BITBLT flag. 
Parameters 
hDestDC HDC: The destination device context handle. 
Xx int: The logical X coordinate of the upper left corner of the destination rectangle. 
Y int: The logical Y coordinate of the upper left corner of the destination rectangle. 
nWidth — int: The width, in logical units, of the destination rectangle. 
nHeight int: The height, in logical units, of the destination rectangle. 
hSrcDC HDC: The device context from which the bitmap will be copied. This is normally a memory device 
context created with CreateCompatibleDC(). A bitmap is loaded into the memory device context. 
using SelectObject(). 
XSYrc int: The logical X coordinate of the upper left corner of the source bitmap. Normally, zero. 
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YSre i _ int: The logical Y coordinate of the upper right corner of the (a Ee 


source bitmap. Normally, zero. ona | 
nSrcWidth . int: The width, in logical units, of the source bitmap. If the ; —— 
default coordinate system is being used for hSrcDC, this is the : ; 
width in pixels. 
nSrcHeight — - int: The height, in- logical units, of the source pitian. If the 
default coordinate system is being used for hSrcDC, this is the 
height in pixels. COLORONCOLOR 
dwRop - ~~ DWORD: One of the raster-operation des: Fifteen of the 256 Figure 15-17. StretchBl( ) 


- possibilities have names that are defined in WINDOWS.H and Example. 
are listed in Table 15-9. The remainder have hexadecimal 
codes, specified in Volume 2, Section 11, Table 11.3 of the Microsoft SDK Reference manuals. 
_. These codes determine how the colors of the brush are combined with the existing colors of 
.. the background. For the Boolean codes, “S” is the source bitmap, “D” is the destination bitmap, 
and “P” is the currently selected brush tet a en. The Boolean cherors Oy the Cc 
nae “language. conventions. gene a : rt eee 


BLACKNESS Turns all output black. (0) 


’ DSTINVERT Inverts the destination bitmap. (~D) 
MERGECOPY __ The source and destination bitmaps are combined with the Boolean AND operator. (D & S) 
MERGEPAINT '* The source and destination bitmaps are combined with the Boolean OR operator. (~S 1D) 
NOTSRCCOPY Inverts the source bitmap, then copies it to the destination. (~S) . 
NOTSRCERASE Inverts the result of combining the source and destination bitmaps using the Boolean XOR 
a opera-tor. (~(S1D)) 1. iro 
PATCOPY . Copies the pattern to the destination. (P) 
PATINVERT om Combines the destination ae with the patem using the Boolean XOR operator. p ‘D) 
PATPAINT oe oe AP | ~(S iD) ar ; 
~SRCAND _ | ; Combines the source and destination bitmaps with the. Bacar AND operator (S g D) 
SRCCOPY . a Be hs Copies the source to the destination. (S) 
SRCERASE $&~D 
SRCINVERT Combines the source and destination bitmaps using the Boolean XOR operator. (S “ D) 
SRCPAINT Combines the source and destination bitmaps using the Boolean OR operator. (S | D) 
WHITENESS Turns ail output white. This is a quick way to blank a device context. (1) 
Table 15-9. Raster-Operation Codes. | | 
Example This example, shown in Figure 15-17, uses StretchBlt() four times to draw the same bitmap in 


four different sizes. The stretching mode is set to COLORONCOLOR prior to using StretchBIt(). ° 
GetStretchBltMode() is used at the end of the output session to demonstrate that the stretching 
~ mode is still in effect. The current stretching mode is output under the bitmaps. 


long FAR PASCAL WndProc CHWND bunds unsigned iMessage, WORD wParam, LONG lParam) 
{t 


static HBITMAP _ hBitmap ; 

HDC : hDC, hMemDC ; 

int nStrMode ; 

switch (iMessage) ‘ ’ /* process windows messages */ 


- a 
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case WM_CREATE: 
hBitmap = LoadBitmap (ghInstance , “pen") ; 
break ; 

case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_DOIT: /* User hit the “Do it" menu item */ 

hDC = GetDC ChWnd) ; 

hMemDC = CreateCompatibleDC (hDC) ; 

SetStretchBltMode (hDC, COLORONCOLOR) ; 

SelectObject (hMemDC, hBitmap) ; 

StretchBlt (hdc, 10, 10, 200, 80, hMemDC, 
, 0, 60, 60, SRCCOPY) ; 

StretchBlt ChDdC, 10, 10, 106, 40, hMemDC, 

0, 0, 60, 60, SRCCOPY) ; 

StretchBlt Choc, 10, 10, 50, 20, hMemDC, 
, 0, 60, 60, SRCCOPY) ; 

StretchBlt ChdC, 10, 10, 25, 10,,hMembC, 

, 0, 60, 60, SRCCOPY) ; 
DeleteDC ChMembe) ; 


nStrMode = GetStretchBltMode ChDC) ; 
switch (nStrMode) 
{ 


case WHITEONBLACK: 
TextOut (hdc, 10, 100, 
“WHITEONBLACK", 12) ; 
break ; 
case BLACKONWHITE: 
TextOut (hOC, 10, 100, 
“BLACKONWHITE", 12) ; 
break ; 
case COLORONCOLOR: 
TextOut (hdc, 10, 100, 
“COLORONCOLOR", 12) ; 
break ; : 
} 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break > 
} 
break ; 
case WM_DESTROY: /* stop application */ 
DeleteObject (hBitmap) ; 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return COL) ; 
} : 


STRETCHDIBItTs O Win 2.0 Win3.0 mWin3.1 


Purpose Paints from a device-independent bitmap (DIB) aneely to a device context, stretching and/or 
compressing the image as it is painted. 


Syntax _ WORD StretchDIBits(HDC hDC, WORD DesiX, WORD DestY, WORD wDesiWidth, WORD 
wDestHeight, WORD SrcX, WORD SrcY, WORD wSrcWidth, WORD wSreHeight, LPSTR lpBits, 
LPBITMAPINFO [pBitsInfo, WORD wUsage, DWORD dwRop) ; 

Description This function is similar to SetDIBitsToDevice(). The bitmap can be stretched and/or compressed 
as it is painted to the device context. No provision is given for banding the output (painting the 


bitmap in sections to conserve memory), so the entire bitmap must be output in one call to 
StretchDIBits(). 
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Uses 


Returns 
See Also 


Parameters 
hDC 


DestX 


DestY 
wDestWidth 
‘wDestHeight 

_ Srex 

SrcY 
wSrcWidth 
wSrcHeight 
lpBits 


lpBitsInfo 


wUsage 


dwRop 


This function will output to a memory device context, unlike SetDIBitsToDevice(), which 
only outputs to a physical device context. If the image is compressed, bits will be eliminated from 
the output. How this is done is controlled by the SetStretchBltMode(Q) function. The image can be 
reversed or inverted by using unmatched signs (one positive, one negative) for the source and 
destination width or height parameters. 

Like SetDIBitsToDevice(), this function will not preserve the color data in the DIB header. 


The colors in the DIB will be mapped to the existing color palette. To preserve the color informa- 


tion, the DIB color data must be used to realize a logical palette. There is an example of this in 
the beginning of this chapter under the section DIB Example. 


Convenient if the bitmap image must be scaled to fit a particular space. The images on the left 
side of the Windows PaintBrush application are good examples. They change size depending on 
the size of the parent windows. 

The return value is the number of lines of pixels copied. Zero on error. 


CreateDIBitmap(), GetDiBits(), SetDIBitsToDevice() 


HDC: The device context on which the DIB will be output. This can be a physical device or a 
memory device context created with CreateCompatitleDC(). 


WORD: The logical _X coordinate on the device context to start the bitmap output. The logical 
units equal pixels unless the mapping mode has been changed. 

WORD: The logical Y coordinate on the device context to start the bitmap output. 

WORD: The width, in logical units, of the output bitmap. 

WORD: The height, in logical units, of the output bitmap. ’ 
WORD: The X position in the DIB from which to start reading pixel data for output. Normally 0. 
WORD: The Y position in the DIB from which to start reading pixel data for output. Normally 0. 
WORD: The width, in pixels, of the memory bitmap pointed to by lpBits. | 

WORD: The height, in pixels, of the memory bitmap pointed to by /pBits. 

LPSTR: A pointer to the memory buffer that contains the pixel data. Normally, this follows the 
BITMAPINFO header data in a memory buffer. The pixel data can be in a separate buffer. 


LPBITMAPINFO: A pointer to an initialized BITMAPINFO data structure. This data describes 
the size and color data for the bitmap. See Created IDianan@ fora eecBHan of this data struc- 
ture. 


WORD: Specifies whether the bmiColors{] fields at the end of the BITMAPINFO data structure 
contain explicit RGB color values, or if they are indexes into the currently realized logical pal- 
ette. wUsage can be either DIB_PAL_COLORS for palette colors, or DIB_RGB_COLORS for ex- 
plicit RGB colors. . 


DWORD: One of the raster-operation codes. Fifteen of the 256 possibilities have names that are 
defined in WINDOWS.H and are listed in Table 15-10. The remainder have hexadecimal codes, 
specified in Volume 2, Section 11, Table 11.3 of the Microsoft SDK Reference manuals. . 

These codes determine how the colors of the brush are combined with the existing colors of 
the background. For the Boolean codes, “S” is the source bitmap, “D” is the destination bitmap, 
and “P” is the currently selected brush (called a “pattern”). The poole operators follow the C 
language conventions. - 


706 


15. BITMAPS V 


Py 


so tte 
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Turns all output black. (0) 
DSTINVERT "Inverts the destination bitmap. (~D) 
MERGECOPY The source and destination bitmaps are combined with the Boolean AND operator. (D & S) 
MERGEPAINT . * The source and destination bitmaps are combined with the Boolean OR operator. (~S | D) 
NOTSRCCOPY Inverts the source bitmap, then copies it to the destination. (~S) 
NOTSRCERASE _ Inverts the result of combining the source and destination bitmaps using the Boolean OR 
operator. (~(S | D)) 
_ PATCOPY Copies the pattern to the destination. (P) . 
” PATINVERT Combines the destination bitmap with the pattern using the Boolean XOR operator. (P “ D! 
PATPAINT P | ~(S ID) 
SRCAND Combines the source and destihation bitmaps with the Boolean AND operator. (S &'D) 
SRCCOPY Copies the source to the destination. (S) 
SRCERASE S&~D 
SRCINVERT . Combines the source and destination bitmaps using the Boolean XOR operator. (S 4 D) 
SRCPAINT Combines the source and destination bitmaps using the Boolean OR operator. (S | D) 
WHITENESS Turns all output white. This is a quick way to blank a device context. (1) 
Table 15-10. Raster-Operation Codes. 
Example This example creates a colored DIB in memory when the 


WM_CREATE message is processed. The image is painted on 
the window’s client area every time a WM_PAINT message is 
processed. StretchDIBits() paints by compressing the horizon- 
tal dimension by two-thirds and expanding the vertical size by 
a factor of two. Compare this figure with the nonstretched im- 
age under the SetDIBitsToDevice() example. 

The example code also demonstrates changing the pixel 
data in the bitmap. In this case, when the user clicks the “Do 
It!” menu item, any set of two black pixels (color value equals 
OxFF with a 16-color bitmap) are changed to two white pixels 
(color value of 0x00). This is a device-dependent way to change 
colors, and is unusual. Normally, the bitmap data would be re~ Boome: iro 
painted using GDI functions, as demonstrated with the code Figure 15-18. Stretch- 


— generic] |* 


Do It! Quit 


under the WM_CREATE message. DIBiis() Example. 
fidefine ALIGNLONGCi) CCi43)/4%4) 
H#define WIDTH ~ 150 
Hdefine HEIGHT 50 : 
#define COLORBITS 4 i. 


long FAR PASCAL WndProc (CHWND hWnd, unsigned. iMessage, WORD wParam, LONG lParam) 
{ : 
PAINTSTRUCT a ps ; 
static BITMAPINFOHEADER bi; 


4 
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LPBITMAPINFOHEADER ; lpbi ; 


LPBITMAPINFO ; LpBitInfo ; 

static - HBITMAP — hBitmap ; 

HDC . hDC, hMemDC ; 

static HANDLE heIB ; 

HBRUSH hBrush ; 

LPSTR LpstBitmap, lpstTemp ; 
int ; i, nBytes ; 

switch CiMessage) pa _/* process windows messages */ 

{ - . 


case WM_CREATE: 

hDC = GetDC ChWnd) ; 

7* initialize BITMAPINFOHEADER data */ 
bi.biSize = sizeof (BITMAPINFOHEADER) ; 
bi.biWidth = WIDTH ; /* 8 by 8 bitmap */ 
bi.biHeight = HEIGHT ; ; 
bi.biPlanes = 1; 
bi.biBitCount = COLORBITS 
-bi.biCompression = BI_RGB 
bi.biSizeImage = (ALIGNLONGC (WIDTH * COLORBITS)/8) 

* HEIGHT); 
bi.bixPelsPerMeter 
bi.biYPelsPerMeter 
bi.biClrUsed = 0 ; 
bi.biClrImportant = 0 ; 

/* create uninitialized DIB bitmap */ 
hBitmap = CreateDIGitmap €hDC, &bi, OL, NULL, 

NULL, 0) ; 

/* atlocate: memory for BITMAPINFO structure */ 


/* 16 colors on screen */ 


Se Ne 


0; 


hDIB = GlobatAlloc (GHND, sizeof CBITMAPINFOHEADER) + 
16 * sizeof (RGBQUAD) + | 
CALIGNLONGCCWIDTH * COLORBITS)/8) * HEIGHT)); 
Lpbi = (BITMAPINFOHEADER FAR *) GlobalLock ChDIB) ; 


/* tricky way to copy bi to top of BITMAPINFO */ 
*lpbi = bi ; 
/* use GetDIBits() to init lpbi struct data */ 
GetDIBits (hDC, hBitmap, 0, 50, NULL, 
' CLPBITMAPINFO) ipbi, « DIB_RGB_COLORS) ; 


/* create memory device context */ 
hMemDC = CreateCompatibleDC ChDC) ; 

/* select DIB bitmap into device context */ 
SelectObject (hMemDC, hBitmap) ; 

/* paint on memory device context */ 
hBrush = CreateSolidBrush (RGB (255, 80, 80)) ; 
SelectObject (hMemDC, hBrush) ; 

Rectangle (hMemDC, 0, 0, WIDTH, HEIGHT) ; 
DeleteObject (SelectObject ChMemDC, 

~GetStockObject (WHITE_BRUSH))) ; 
Ellipse (hMemDC, 0, 0, WIDTH, HEIGHT) ; 
hBrush = CreateSolidBrush (RGB 0, 0, 255)) ; 
SelectObject (hMemDC, hBrush) ; 
Ellipse (hMemDC, WIDTH / 3, 0, 5 * WIDTH / 3, HEIGHT) ; 
DeleteObject (SelectObject ChMemDC, 

GetStockObject (BLACK_BRUSH))) ; 
Ellipse (hMemDC, 2 * WIDTH / 5, HEIGHT / 5, 

3 * WIDTH / 5, 4 * HEIGHT / 5) ; , 

/* set pointer to bitmap's bit data */ 
lpstBitmap = CLPSTR) Lpbi + : 

CWORD) sizeof (BITMAPINFOHEADER) + 

(16 * sizeof (RGBQUAD)) ; 

GetDIBits (hDC, hBitmap, 0, HEIGHT, LpstBitmep, 

CLPBITMAPINFO) Lpbi, DIB_RGB_COLORS) ; 
GlobalUnlock pete) ; 

DeleteDC ChMemDC) ; 
Re lessen’ ChWnd, pecs 
break ; j 
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case WM_PAINT: 
s BeginPaint (hWnd, &ps) ; 
SetStretchBltMode Cps.hdc, COLORONCOLOR) ; 
LpBitInfo = (LPBITMAPINFO) GlobalLock C(hDIB) ; 
LpstBitmap = C(LPSTR) LpBitInfo + 
CWORD) sizeof (BITMAPINFOHEADER) + 
(16 * sizeof (RGBQUAD)) ; 
StretchDIBits (ps.hdc, 10, 10, 2 * WIDTH / 3, 
HEIGHT * 2, 0, 0, WIDTH, HEIGHT, 
LpstBitmap, lpBitInfo, DIB_RGB_COLORS, 
SRCCOPY ) ; 
GlobalUnlock (hDIB) ; 
EndPaint (hWnd, &ps) ; 
break ; 
_case WM_ COMMAND: /* process menu items */ : ’ 
’ switch (wParam) 
{ 
case IDM_DOIT: /* change black pixels to white */ 
hOC = GetDC ChWnd) ; 
Lpbi = (BITMAPINFOHEADER FAR *) GlobalLock (hDIB) ; 
LpstBitmap = (LPSTR) Lpbi + 
(WORD) sizeof (BITMAPINFOHEADER) + 
(16 * sizeof CRGBQUAD)) ; 
nBytes = ALIGNLONG( (WIDTH * COLORBITS)/8) * HEIGHT ; 
; /* copy bitmap bytes into temp buffer */ 
\LpstTemp = LpstBitmap ; 
‘for Ci = 0; i < nBytes ; i++) 


{ 
: if (0 == *lpstTemp) 
*tpstTemp = Oxff ; 
lLpstTempt+ ; 
} 


SetDIBits (hDC, hBitmap, 0, HEIGHT, EPS cht sap, 
SPER PALS NEO? Lpbi, DIB_RGB_COLORS) ; 
ReleaseDC (hWnd, node 
GlobalUnLock (hDIB) ; . 
InvalidateRect (hWnd, NULL, TRUE) ; /* paint */ 
break ; 
‘case IDM_QUIT: /* send end cf application message */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
GlobalFree (hDIB) ; 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, (Param) ; 
} 
return (OL) >; ; 
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- Icons are small bitmaps that Windows uses as visual placeholders for applications. They are the small pictures you see. at 
the bottom left corner of the screen when applications are minimized. Putting some time into an attractive program icon 
is well worth the effort because the icon is frequently the image that sticks in the user’s mind when he or she thinks of the 
program. Figure 16-1 depicts three typical icons. 


Using Icons 


Normally, you will create an icon using the Windows SDKPaint application, and add it to the program's resource file. 
A typical resource file is shown below. 


/* generic.rc */ 


#include <windows.h> 
#include “generic.h" 


generic ICON generic.ico 

childic ICON child.ico 

generic MENU ’ 

BEGIN ; ; 
MENUITEM "&Do It!” IDM_DOIT 
MENUITEM “&Quit", IDM_QUIT 

END 


In this example two icon files are included in the program’s resources. Both icons are given names (“generic” and 
“childic”) that are used to reference them when they are loaded. An icon can be associated with a window class. An 
application normally does this in the WinMain() function. 


wndclass.hIcon = LoadIcon (hInstance, ‘“generic") 3 


With an icon loaded as part of the window's class 
structure, the icon will be painted automatically if the 
window is minimized. Windows will send WM_PAINT- ; a”) Cok am 
ICON messages when the icon is about to be painted, Sr rs Spe ee ere 
rather than WM_PAINT messages. Every window created 
from the same class will have the same class icon. Note 3 A op J Cl 0 ck 0 siram er 
that the program’s instance handle (hJnstance) is Figure 16-1. Program Icons. 
needed with the Loadicon() function because resources, 
such as icons, are associated with the program’s data, not the program's code. Each instance has its own data. 

If the window class does not load an icon, the window will not display an icon when it is minimized. 


wndclass.hicon = NULL ; 


In this case, the application can paint on the small bit of window client area that is visible when the application 
is minimized using the normal GDI painting functions. WM_PAINT messages are sent to the application when the 
minimized window needs to be painted. The IsIconic() function can be used to determine if the window is minimized. 
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WM_PAINT messages will not be sent to a minimized window if an icon is specified in the window's class definition 
(see RegisterClass(}). 

Applications that use a number of child windows that can be minimized end up with a number of icons. Minimiz- 
ing a child window causes Windows to display the child window icon at the bottom of the parent window’s client area. 
These icons can be dragged with the mouse within the bounds of the client area. The convenient function 
ArrangelconicWindows() is provided to neatly arrange all of the icons at the bottom left corner of the client area. 


Creating Icons at Run Time 


Windows 3.0 allows icons to be created and modified while the program is running. The CreateIcon() functicn is 
similar to CreateCursor(). They both create an image by combining two bitmaps. CreateIcon() has the ability to 
create icons from a binary array, bitmap data, and device-independent bitmaps. The Destroylcon() function is pro- 
vided to delete an icon created with CreateIcon(), freeing memory consumed by the icon’s data. Exercise restraint 
when creating and modifying an icon as 
the program operates. Users expect 
icons to remain unchanged. If the appli- 
cation needs to make the minimized win- 
dow change (small clock applications . 
are an example), it is simpler not to load a class icon, and just paint on the minimized window's client area. 

Although it is seldom necessary to work with the internals of an icon, its structure is worth knowing. The icon 
resource file consists of two data structures, a header and one or more icon descriptions. (See the illustration in 
Figure 16-2.) 

Although the structures are not defined in WINDOWS.H, you can define your own to manipulate the icon data. The 
header has the following format: 


typedef tagIlconHeader; 
{ 


WORD jicoReserved ; /* must be zero */ 
WORD icoResourceType ;- /* the type of resource, 1 for icons */ 


WORD icoResourceCount; /* the number of icons defined in this file */ 
} IconHeader ; . 


Each icon defined in the file (there will be iconResourceCount of them, normally one) will have the following 
structure: . 


typedef tagIiconData; 
{ 


‘ 


BYTE Width ; /* jcon width in pixels, 16, 32, or 64 */ 
BYTE Height ; /* icon height in pixels, 16, 32, or 64 */ 
BYTE ColorCount ; -/* the number of colors, 2, 8, or 16 */ 
BYTE Reserved! ; /* reserved for future use */ 

WORD Reserved2 ; '/* reserved for future use */ 

WORD Reserveds3 ; _ /* reserved for future use */ 

DWORD icoDIBSize ; /* the size of the pixel array */ 


DWORD icoDIBOffset ; /* the number of bytes from the beginning of */ 
/* the file to the DIB bitmap for this icon */ 
+ IconData ; 


The actual bitmap data consists of two parts. The first (called the XOR mask) is the color bitmap for the image. It 
is followed by a second, monochrome bitmap, called the AND mask. The AND mask is used to mark the transparent 
and opaque pixels of the icon. Note that the icon bitmap size for both the vertical and horizontal dimensions is limited 
to one of three values: 16, 32, or 64 pixels. Similarly, the number of colors can be only 2, 8, or 16. 

Because the header allows more than one icon to be defined in one resource file, you can build an icon file with 
three different sizes, or with different color resolutions. Windows will pick the best match of resolution and color . 
capabilities when deciding which icons to load. This approach gives a measure of device-independence to icons. 
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Icon Function Summary 
Table 16-1 summarizes the icon functions. The detailed function descripticns are in the next section. _ 


2, 
Wwe Ke in eee * : us 


BaF Scent 


ArrangelconicWindows 


Arranges all minimized child windows in the lower left corner of the parent window's client area. 
Createlcon Creates an icon based on two mernory blocks containing bit data. 
Destroyicon Destroys an icon that was previously created with Createlcon( ) 
Drawicon Draws an icon on a device. 
- Loadicon Retrieves a hancle to an icon listed in the program’s resource file. 


Openlcon Restores a minimized window to its last size and position. 


Table 16-1. Icon Function Summary. 


Icon Function Descriptions 
This section contains the detail descriptions of the icon functions. 


ARRANGEICONICWINDOWS . mWin2.0 mWin30 mWin3.1 
Purpose Arranges all minimized child windows in the lower left corner of the parent window’s client area. 
Syntax WORD ArrangelconicWindows(HWND hWnd); 

Description Applications that use a number of child windows that can be minimized or restored run into the 


problem where some child window icons are covered up by other child windows. Arrange- 
IconticWindows() puts all iconic windows in a row, starting at the lower left corner of the parent 
window's client area. If there is not enough room for all of the icons, additional rows of icons are 
created above the first one. This procedure mimics the behavior of the program manager 
application’s positioning of group boxes and Windows’ positioning of program icons on the back- 
ground. 

Uses Used with applications that have child windows that can be minimized. ArrangelconicWindows() 


can also be used to arrange the program icons at the bottom of the screen. Use GetDesk- 
topWindow() to retrieve the desktop window handle. 


Returns WORD, the height of one row of icons, measured in pixels. Zero if there were no icons associated 
- with hWnd. 

See Also GetDesktopWindow(), OpenIcon(), Chapter 29 on MDI applications. 

Parameters . 


hWnd HWND: The parent window handle. ste Sgenerie’s oa 


Bolt! Quit 


Related Messages WM_SIZE. An application can call ArrangelconicWindows() for 

the desktop background (using GetDesktopWindow() to retrieve 

the background handle) every time a WM_SIZE message passes 

a SIZEICONIC value. Using this function assures that all program 

icons, including the application that was just minimized, are ar- 
ranged at the bottom left of the screen. Figure 16-3, Arrange- 

IconicWindows() and — 
Opentcon() Example. 


hild ‘WindosChild Window 2 


Example This example.creates two child windows that have their own win- 
dow class, and share the same message processing procedure, 

- ChildProc(). (See Figure 16-3.) The child windows are initially 

shown minimized, and arranged at the lower left of the parent window's client area. When the user 

licks the “Do It!” menu item, one of the child windows is restored to its normal size with OpenIcon(), 
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and the remaining minimized child window is arranged at the lower left corner with Arrange- 
IconicWindows(). 

The child window message-processing function “ChildProc” must be listed in the EXPORTS sec- 
tion of the program’s .DEF definition file. A function prototype should also be added to the 
header file. 

Note in the listing that the client area of the parent window is repainted before the iconic 
windows are arranged (InvatidateRect() and SendMessage() function calls). They are repainted 
because Windows will not erase the lettering under the iconized windows when they are restored 
to normal size. Repainting the client area before the icons are arranged solves this problem. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 


HDC hDC ; 
WNOCLASS wndclass } 
static HWND hChild1, hchild2 ; 
switch CiMessage) /* process windows messages */ 
{ 
case WM_CREATE: 7* build the child windows */ 
wndclass.style = CS_HREDRAW | CS “VREDRAW | 


CS_PARENTDC; 
wndclass.lpfnWndProc 
wndclass.cbClsExtra 
wndclass.cbWndExtra 
wndclass.hInstance 
wndclass.hIcon 

IDI_APPLICATION) ; 
wndclass.hCursor 

IDC_ARROW) ; 
wndclass. RecuacLerouna = 

GetStockObject (LTGRAY_BRUSH) ; 
wndclass.lpszMenuName jezAogilawé 7 
wndclass.tpszClassName “SecondClass” ; 
if(RegisterClass (&wndclass)) = 


ChildProc ; 

0; 

0; 

ghInstance ; 
LoadiIcon (NULL, 


LoadCursor (NULL, 


{ 
hChild1 = CreateWindow ("SecondClass", 
“Child Window 1", 
WS_CHILD | WS_VISIBLE | WS_CAPTION | 
WS_BORDER, 10, 50, 200, 150, hWnd, 
= NULL, ghInstance, NULL) ; 
ShowWindow (hChildi1, SW_SHOWMINIMIZED) ; 
hChild2 = CreateWindow ("SecondClass", 
“Child Window 2", 
WS_CHILD | WS_VISIBLE | WS_CAPTION | 
WS_BORDER, 100, 30, 150, 100, hWnd, 
NULL, ghInstance, NULL) ; 
ShowWindow (hChild2, SW_SHOWMINIMIZED) ; 
ArrangelconicWindows (hWnd) ; 
} 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_DOIT: 
Openicon ChChild1) ; 
InvalidateRect (hWnd, NULL, TRUE) ; 
SendMessage (hWnd, WM_PAINT, 0, OL) ; 
ArrangeiconicWindows (hWnd) ; 


break ; 

case IDM_QUIT: _ /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
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} 


break ; ; 

case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 


default: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


a; 


/* Here is a separate message procedure for the child window */ 


long FAR PASCAL ChildProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


{ 


PAINTSTRUCT ps ; 


switch (iMessage) /* process windows messages */ 


} 
} 


CRrEATEICON 
Purpose 
Syntax 


Description 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
TextOut (ps.hdc, 0, 0, "I'ma child.", 12) ; 
EndPaint (hWnd, &ps) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


OC Win 2.0, Win3.0 wWin3.1 
Creates an icon based on two memory blocks containing bit data. 


HICON CreateIcon(HANDLE hJnstance, int nWidth, int nHeight, BYTE nPlanes, BYTE 
nBitsPixel, LPSTR lpANDbits, LPSTR lpXORbits); 

Normally, icons are created using the Windows SDKPaint application and added to the program 
as resources. Createlcon() provides an alternative, creating icon images dynamically as the program 
operates. The icon can be created from binary data, a bitmap, or a device-independent bitmap (DIB). 
The icon is created by combining two bitmaps, the AND mask, and the XOR mask. The AND mask is 


always a monochrome bitmap, with one bit per pixel. Table 16-2 shows how the two bitmaps are 
combined. 


Black 


0 

1 White 

0 Transparent 
1 | Inverted color 


Table 16-2. Monochrome Icon Bit Masks. 


Uses 


Returns 
See Also 


If the XOR bit mask is replaced with a bitmap or DIB, set the AND mask to all ones (OxFF bytes). 


Can be used to provide bitmaps that change as an application runs. Users expect icons to retain 
the same shape, so change bitmaps cautiously. Note that an application can paint on the small 
amount of window area that shows when the window is iconic, if the window’s class definition 
does not load a class icon. This is the normal way to change the appearance of an iconic window. 


HICON, the handle to the icon created. NULL on error. 
Deletelcon(), GetSystemMetrics() 
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Parameters 
hInstance HANDLE: The program’s instance handle. 
nWidth int: The width, in pixels, of the icon. Use GetSystemMetrics(SM_CXICON) to retrieve this value. 
nHeight int: The height, in pixels, of the icon. Use GetSystemMetrics(SM_CYICON) to retrieve this value. - 
nPlanes int: The number of color planes in the XOR mask for the icon. For example, | for monochrome, 4 
for 16-color VGA, etc. 
nBitsPixel int: The number of bits per pixel in the XOR mask for the icon. Again, | for monochrome, 4 for 16 
colors. One or both of nPlanes and nBitsPixel must be set to 1. 
lpANDbits LPSTR: A pointer to an array of monochrome bits, specifying the AND mask for the icon. The 
AND mask determines the opaque and transparent portions of the icon. Set to 1 for opaque. 
lpXORbits LPSTR: A pointer to an array of bits specifying the XOR mask for the icon. Alternatively, the 
pointer can point to a memory block containing a monochrome bitmap or device-dependent color 
bitmap (DDB). 
Example This example creates a monochrome icon, illustrated in Figure ay 7 
16-4, by directly specifying the bit values of boththe AND mask [RRBs ?réaand f 3 
_ and the XOR mask of the icon. The icon is created when the Do lt! Quit 
WM_CREATE message is processed, and it is painted to the §— = 
client area when a WM_PAINT message is received. Theiconis | 
destroyed as the application terminates. } al | 7 
Note in the listing that the data defining the bitmap is | 
freed from memory after the icon is created. The icon will con-  Becexmremmscremesm 
tain valid bitmap data from the time it is created, until Figure 16-4. Createlcon() 
DestroylIcon() is called. and DeleteIcon() Example. 
#define EVENBYTE(i) (C447) /8*8) 


Long FAR PASCAL WndProc (CHWND hWnd, unsigned iMessage, WORD wParam, LONG. lParam) 
{ 


PAINTSTRUCT ps ; 

static HANDLE hANDBits, hXORBits ; 

PSTR PpsAND, psXOR, psA, psX ; 

static int nIconWide, niconTall ; 

int i, j, nIconBytes ; 

static HICON hIcon ; 

switch CiMessage) /* process windows messages */ 
{ 


case WM_CREATE: ; 
niconWide = GetSystemMetrics (SM_CXICON) ; 
niconTall = GetSystemMetrics (SM_CYICON) ; 
niconBytes = CEVENBYTE (nIconWide) / 8) * nIconTall ; 
hANDBits = LocalALloc CLMEM_MOVEABLE, nIiconBytes) ; 
hXORBits = LocalAlloc CLMEM_MOVEABLE, niconBytes) ; 
. PSA = pSAND = LocalLock C(hANDBits) ; 


psX = psxOR = LocalLock ChXORBits) ; 
for (i = 0 ; i < EVENBYTE (niconWide) / 8 ; i++) 
{ 
for (j =O; j < nIconTall ; j++) 
*psAt+ = OxFF ; 
if Ci > j) 
*psxXt++ = OxFF ; 
else 
*psX++ = 0x11 ¢ 
- Ss 
} 
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} 


DESTROYICON 


Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
hIcon 


Example 


DrawIicon 
Purpose 
Syntax 
Description 


Uses 
Returns 
See Also 


return (OL) ; 


hIcon = CreatelIcon (ghInstance, niIconWide, 
nIconTall, 1, 1, psAND, psXOR) ; 
LocalUnlock ChANDBits) ; 
LocalUnlock ChXORBits) ; 
LocalFree ChANDBits) ; 
LocalFree ChXORBits) ; 
break ; 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
DrawIcon (ps.hdc, 10, 10, hIcon) ; 
EndPaint (hWnd, &ps) ; 
break ; 
case WM_COMMAND: 
switch (wParam) 


/* process menu items */ 


case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: 
Destroylcon ChIcon) ; 
PostQuitMessage (0) ; 
break ; 
default: 


/* stop application */ 


/* default windows nessage processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


# 


OWin2.0 mWin3.0 mWin31 
Destroys an icon that was previously created with CreateIcon(). 


BOOL DestroyIcon(HICON hlcon); 


Destroying an icon removes the icon data from memory. This should only be used for icons cre- 


ated using CreateIcon(). 


Used to free memory once the icon is no longer needed. Do not call Destroylcon() if the icon is in 
use. ; 


BOOL. TRUE if the icon was destroyed, FALSE on error. 
CreateIcon() 


HICON: The handle of the icon, returned by CreateIcon() when the icon was created. 
See the previous example under Createlcon(). 
Win 3.1 


f Win 2.0 Win 3.0 


Draws an icon on a device. 


~~ BOGL Drawlcon(HDC ADC, int.X, int ¥, HICON hlcon); 


This is the only function for painting icons. The icon is normally loaded from the resource data 
using LoadIcon(). It can also be created using CreateIcon(). The device context must be in the 
MM_TEXT mapping mode for this function to operate properly. 


Drawing an icon. 
BOOL. TRUE if the icon was drawn, FALSE on error. 
LoadIcon(), Createlcon() 
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HDC: The device context handle. 


int: The logical X coordinate of the upper left corner of the 
icon. 


Do It! 


int: The logical Y coordinate of the upper left corner of the 
icon. 


HICON: The handle of the icon. This value is returned either 
by LoadIcon() or Createlcon(). 


This example, as shown in Figure 16-5, paints all five stock  /#9ure 16-5. LoadIcon() and 
icons to the screen, and also paints the GENERIC application's | 27aw/con Example. 

icon on the lower left. Froin left to right, the five stock icons on 

the top row are named IDI_APPLICATION, IDI_ASTERISK, IDJ_EXCLAMATION, IDI_HAND, and 
IDI_ QUESTION. The image and the name of the IDI_ ASTERISK and IDI_HAND icons do not match 
because the icons were a different shape with the 2.0 release of Windows. 


tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 
static HICON hIcon1, hIcon2, hIcon3, hicon4, hIcon5, hicon6é ; 
\ 
switch (iMessage) /* process windows messages */ 
{ 


case WM_CREATE: 


hIcon1 = LoadIcon (NULL, IDI_APPLICATION) ; 
hIcon2 = LoadiIcon (NULL, IDI_LASTERISK) ; 
hIcon3 = Loadicon (NULL, IDI_LEXCLAMATION) ; 
hIcon4 = Loadicon (NULL, IDI_HAND) ; 

hIcon5 = Loadicon (NULL, IDI_QUESTION) ; 
hIcon6 = Loadicon (ghInstance, “generic") ; 
break ; 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
Drawlcon (ps.hdc, 10, 10, hIcon1) ; 
Drawlcon (ps.hdc, 50, 10, hIcon2) ; 
Drawlcon (ps.hdc, 90, 10, hIcon3) ; 
DrawIcon (ps.hdc, 130, 10, hIcon4) ; 
DrawIcon (ps.hdc, 170, 10, hIcon5) ; 
Drawlcon (ps.hdc, 10, 60, hIicon6) ; 
EndPafnt (hWnd, &ps) ; 


break ; 
[Other program lines] 
LoapIcon BWin2.0 wm Win3.0 Win 3-1 
Purpose . Retrieves a handle to an icon listed in the program’s resource file. 


Syntax 
Description 


HICON LoadIcon(HANDLE hJnstance, LPSTR lpJconName); 


LoadIcon() does two related tasks, It retrieves a handle to an icon referenced in the program’s 
.RC resource script file. It also retrieves stock icon images. If more than one call to LoadIcon() is 
made for the same icon name, a handle is retrieved to the existing icon data in memory. Normally, 
icons are created with the Windows SDKPaint application and stored in a disk file. A program can 
use the icon by including an ICON statement in the .RC resource file. 

generic ICON generic.ico 

Then, the program can obtain a handle to the icon using the icon’s name, “generic” in this case. To 
load a stock icon, the kInstance parameter must be set to NULL. 
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Uses. 
Returns 
See Also 


Parameters 
hInstance 


lpIconName 


IDI_APPLICATION 
~ IDI_ASTERISK 
IDI_EXCLAMATION 
iDI_HAND 
ID|_QUESTION 


Obtaining a handle to an icon, ready to use for DrawIcon(). 
HICON, the handle to the icon. NULL on error. 
DrawlIcon() 


HANDLE: The application’s instance handle. Use GetWindowWord() to obtain this value if it has 
not been saved. Set to NULL to load a stock icon. 


LPSTR: A pointer to a character string containing the name of the icon. (This is the name on the 
left side of the ICON statement in the application’s .RC resource file.) If hInstance is set to NULL, 
lpIconName can be one of the five stock icon names listed in Table 16-3. 


x caning. Se ae ae 


The default application icon, an open rectangle. 


An information icon. 

An exclamation point icon (for warning messages). 
A stop sign icon (for serious waming messages). 
A question mark. 


Table 16-8. Stock Icons. 


Example 


OpeENICON 
Purpose 
Syntax 
Description 


Uses 
Returns 
See Also 


Parameters 
hWnd 


Related Messages 
Example 


See the previous example under DrawIcon(). 


Win2.0 @Win3d.0 Wind.) 
Restores a minimized window to its last size and position. 
BOOL OpenIcon(HWND hWnd); 


_This is a shortcut method of restoring a window that has been minimized. Windows retains the 


last size and position of the window before it was minimized. Calling OpenIcon() restores the 
window to its former position and size. Note that this function has little to do with the 
application’s icon. It is simply a means of restoring a window. 

Used in applications that have child window controls that can be minimized. 


BOOL. TRUE if the window was restored, FALSE on error. 


 ArrangelIconicWindows() ; e 


HWND: The handle of the window to be restored. This value is returned when CreateWindow() is 
used to create the (child) window. 


WM_SIZE 
See the example under ArrangeiconicWindows(). 
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Windows Sapiies two methods for applications to exchange information: the clipboard and Dynamic Data Exchange 
_(DDE). The clipboard is used for information that is exchanged on demand by the user. DDE is used when the infor- 
mation needs to be transferred in the background, or as it becomes available from some outside source, such as a 
modem. Windows applications use the clipboard frequently. Any time you cut or copy text or bitmaps from within the 
Windows Notepad, PaintBrush, Windows Write, Excel, etc., the data ends up in the clipboard. Because the clipboard 
is available to all applications, you can cut and paste between different programs: This information exchange is a 
powerful feature of Windows, and one of the benefits of using Windows as a development platform. . 


Using the Clipboard 


Physically, the clipboard is just a global memory block. 
When an application gives data to the clipboard, Win- 
dows takes ownership of the memory block. Any applica- 
tion can then request a handle to the memory block and 
read the data. The block remains the property of Win- 
dows. To put data in the clipboard, an application allo- 
cates a global memory block and fills it with data. The 
function SetClipboardData() then passes the memory 
block to Windows. Any application wanting to read the 
memory block can use GetClipboardData() to obtain a 
handle to the global memory location containing the 
_ data. Figure 17-1 shows this relationship graphically. 


SetClipboardData 
A typical program fragment loads a text’string into - 


the clipboard in the follwoing code: Figure 1 7-1, The Clipboard. 


. | GetClipboardData 


hMem = GlobalAlloc-(GHND, 64) ; 

tpStr = GlobalLock ChMem) ; 

istrcpy (lpStr, “Text In Clipboard") ; 
GlobalUnlock (hMem) ; 

if (OpenClipboard ChWnd)) 

{ 


EmptyClipboard () ; 
SetClipboardData (CF_TEXT, hMem) ; 
i CloseClipboard () ; 

The program allocates a global block 64 bytes wide and copies some text to it. The block is then unlocked, but not 
freed. OpenClipboard() alerts Windows that the clipboard is going to be used. If another application has the clipboard 
open, OpenClipboard() will return zero. Otherwise, EmptyClipboard() clears any data currently in the clipboard and 
frees the memory block associated with it. SetClipboardData() adds the new block to the clipboard. i 
lets Windows know that the clipboard is not needed by this application. 

The program code needed to retrieve the text is shown below. 


if COpenClipboard (hWnd)) 
{ 
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hClipMem = GetClipboardData (CF_TEXT) ; 
-hMem = GlobalAlloc CGHND, Stobalsize CcLipHeRD? 5 
ipStr = GlobalLock ChMem) ; 
LpClip = GlobalLock cheLipdand:c 
Lstrepy (lpStr, lpClip) ; 
GlobalUnlock (hMem) ; 
GlobalUnlock ChClipMen) ; 
CloseCiipboard () ; 
} 


Because the global memory block in the clipboard belongs to Windows, the application cannot use it directly. 
Instead, the application needs to copy the data to another memory area that is owned by the application. Again, 
OpenClipboard() alerts Windows that the clipboard will be used, and checks to make sure that no other application 
has the clipboard open. GetClipboardData() obtains a handle to the clipboard’s memory block. The clipboard data is 

then copied into a separate block allocated with GlobalAlloc(). The clipboard memory block is unlocked (but not 
freed) to release the block for use by other applications. CloseClipboard() informs Windows that the clipboard is no 
longer needed. 


Clipboard Formats 


You may have noticed the CF_TEXT string in the SetClipboardData() and GetClipboardData() function calls. This is 
one of several predefined clipboard formats available to all applications. Clipboard formats are used to distinguish 
different types of data that can be exchanged by applications. Without formats, an application might try to read in 
bitmap data and use it as character data. Formats keep the different types of data separate. Table 17-1 lists all of the 
predefined clipboard formats. 


CF_BITMAP . _ Abitmap handle (HBITMAP). 


CF_DIB Amemory block containing a device-independent bitmap (DIB). The block will contain a 
BITMAPINFO data structure followed by the bitmap bits (see Chapter 15, Bitmaps). 

CF_DIF Software Arts’ Data interchange Format. | 

CF_DISPBITMAP A private bitmap display format. 

CF_DSPMETAFILEPICT A private metafile display format. 

CF_DISPTEXT A private text display forrnat. 

CF_METAFILEPICT A metafile picture. The memory block will contain a METAFILEPICT data structure (see Chapter. 
23, Metafiles, and the following discussion). 

CF_OEMTEXT Amemory block containing only OEM text characters. Each line is ended with a CR-LF pair.A - 


NULL byte marks the end of the text. Windows uses this format to transfer data between non- 
Windows and Windows applications. 


CF_OWNERDISPLAY _ The clipboard owner is responsible for painting the clipboard. The clipboard owner should 


process WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, 
WWM_SIZECLIPBOARD, and WM_VSCROLLCLIPBOARD messages. 


CF_PALETTE s A handle to a color palette (see Chapter 12, Color Pallette Control). 
CF_SYLK : Microsoft Symbolic Link (SYLK) format. 
, CFTEXT Amemory block containing text characters. Each line is ended with a CR-LF pair. A NULL byte 
‘marks the end of the text. This is the standard format for exchanging text between Windows 
applications. 
CF_TIFF . Tag Image File Format. 


Table 17-1. Clipboard Data Formats. 
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The predefined formats cover the most common types of data exchange. Even if your application uses specialized 
data fields, it should support at least one of the predefined clipboard formats. For example, a spreadsheet might write 
the selected cell contents to the clipboard using only the CF_TEXT clipboard format. This would lose the formatting 
and calculations in the complete spreadsheet data field, but at least it would allow another application to read the 
character data. 


Multiple Clipboard Formats 


Applications may use specialized data formats to exchange data with the clipboard. Windows supports this with the 
process of “registering” a special format. The RegisterClipboardFormat() function allows applicalions to create cus- 
tom formats. 

Using a spreadsheet as an example, let’s say that the program needs to cut ne paste the complete contents of one — 
or more cells in the spreadsheet. There is a lot of data behind each spreadsheet cell, including the calculation formula 
and text formatting options. If the data were passed as a standard format, such as CF_TEXT, another application 
might read all of the formatting data as text, and end up with a lot of strange characters. . 

The solution is to register a new clinboard format. The format might be called “CELL.” The spreadsheet applica- 
tion cuts and pastes cells by copying memory blocks to and from the clipboard using the CELL format. Another 
application trying to read CF_TEXT format data would not get a handle to this data when it called GetClipboardData 
(CF_TEXT). 

Supporting more than one clipboard fociniak is even more sophisticated than this approach. The clipboard can 
hold more than one memory handle, and each handle can contain data in a different format. Our spreadsheet can 
write the full contents of the cells using the CELL format, and also write the cell text using the simple CF_TEXT 
format. This ability allows a word processor to paste text off of the clipboard, while also allowing the spreadsheet to 
paste the full cell data. . . 

_ Word for Windows provides an excellent example of this type of flexibility. When a block of text is cut or copied ~ 
from within Word for Windows, the clipboard has five separate versions of the text available. They range from the 
_ sophisticated “Rich Text Format” special clipboard format, to the lowly CF_OEMTEXT predefined format. A wide 
range of applications will be able to read the text copied to the clipboard by Word For Windows. The examples under | 
the EnumClipboardFormats() and GetPriorityClipboardFormat() function descriptions provide more details. The lat- | 
ter has an example that provides two clipboard formats at the same time. 


Delayed Rendering of Clipboard Data - 
“Rendering” is an awful word for putting data in the clipboard (“rendering” brings to mind boiling caldrons of fat and. 
lime, but this is a different use of the word). Normally, an application will pass a memory block to the clipboard when 
SetClipboardData() is called. Windows provides another option. If SetClipboardData() is called with a NULL memory 
handle, Windows assumes that the application wants to wait to load the memory block into the clipboard. This is 
called “delayed rendering.” 

There are a couple of reasons why you may want to use delayed rendering. One is if there is a low probability that 
the data will be needed. For example, if the user highlights some text and then presses the (Get) key, he or she 
probably wants to get rid of the text. Loading the memory block into the clipboard takes time and fills up memory 
space. Waiting to see if the user wants the data recovered can save memory and speed up the program. You should also 
use delayed rendering if the clipboard will end up passing a large memory block, or several clipboard formats at once. 
In either case, the memory area filled by the clipboard block will interfere with the operation of other -PeOpratus if 
memory gets tight. It is better to load the data at the moment it is required. 

As previously mentioned, the first step in using delayed rendering of clipboard data is to call SetClipboardData(), 
passing NULL as the memory handle. The clipboard format will be registered with Windows, but no data changes 
hands. If another application attempts to read the specified clipboard format data from the clipboard, Windows will 
send a WM_RENDERFORMAT message to the application that called SetClipboardData(). At this point, the applica- 
tion should pass the memory block containing the requested data by calling SetClipboardData(), with a global memory 
block handle. 
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Applications that use delayed: rendering are also expected to process the WM_RENDERALLFORMATS message. 
This message is sent to the application when the application i is about to exit. The application should pass valid global 
memory block handles to the clipbaord for all formats that the application supports. Doing so will let other applica- 
tions paste from the clipboard after the application exits. Examples of délayed rendering of clipboard data are pro- . 
_ vided under the EnumClipboardFormats() and IsClipboardFormatAvailable() function descriptions. 


Bitmap and Metafile Clipboard Formats 


The CF_BITMAP format specifies the “old” DDB bitmap format. Bitmaps are transferred to the clipboard by passing a 
handle to the bitmap i in place of.a handle to an ordinary memory block. The bitmap handle is returned by the — 
CreateCompatibleBitmap() function, which creates a memory bitmap in global memory. The example under 
SetClipboardData() provides an example program that captures bitmap images from the screen and copies them to 
the clipboard. 
Device- -independent bitmaps (DIBs) are aac to the clipboard as a global memory block. This i is the CF_DIB 
clipboard format. The memory block contains the BITMAPINFO data structure followed by the bitmap bits. Metafiles 
are.transferred to the clipboard using the METAFILEPICT structure, which is defined in WINDOWS. Ha as . 


nypenet struct tagMETAFILEPICT. ; 
‘3 


int “mm; /* the mapping mode */ 


int xExt; /* the metafile X extent (width) */ 
into. yExt; . .. /* the metafile Y extent Cheight) */ 
HANDLE - WMFZ >...) 6 /* a handle to the memory metafile */— 
ie METAFILEPICT; ce 
typedef METAFILEPICT FAR SUPMETAFILEPICT; 


The METAFILEPICT data structure i is initialized i ina global memory block. The hMF element none toa metafile 
in memory (not a disk metafile). When the handle to the METAFILEPICT data structure memory block is passed to 
Windows using SetClipboardData(), both that memory block and the memory block containing the metafile an) 
become the property of Windows. 


Clipboard Viewer Programs 


Windows comes with a clipboard viewer called “Clipboard. . This appiiontion is put i in the Main group when Windows 
is installed. The application will display whatever data is in the clipboard, and will support most of the predefined 
clipboard formats (every one that the author tested). Other applications can be clipboard viewers, and more than one 
clipboard viewer can be active at one time. If more than one application displays the clipboard contents, the applica- 
tions are said to form a “clipboard viewing chain.” The functions SetClipboardViewer() and ChangeClipboardChain() 
are provided to establish an application as a clipboard viewer, and to remove an application from the viewing chain. 
Windows sends clipboard viewers the WM_DRAWCLIPBOARD message when the clipboard data changes. The 
application can display the data (if it supports the clipboard data format). The viewer has the obligation to pass the - 
message to the next viewer in the:chain. When a clipboard viewer is removed from the viewing chain, the 
WM _CHANGECBCHAIN message is sent by Windows. Again, each applicauioy, in thes noe oa is responsible for 
sending this message to the next viewer. : 
- An example of a clipboard viewer that displays both text ail bitmap data is given under the ChangeClip- — 
boardChain() function description. Normally, clipboard viewers are only written to view custom clipboard data for-. 
mats. The Clipboard application supplied with Windows is fine for viewing the standard formats. 

- Caution: Because Windows owns the memory block associated with the clipboard, applications should not jeave : 
this block locked after data has been read. Applications should not allow control to pass back to Windows while the 
clipboard is open. In other words, the clipboard should be opened and closed while processing a single Windows 
message. This can be more complicated than it sounds. For example, an application that opens the clipboard may use 
a dialog box to display an error. If the dialog box is not system-modal, the user can select another application while the: 
dialog box is on the screen. This effectively passes control back to Windows ane the clipboard is still open: Avoid this 
situation by closing the clipboard immediately after use. 
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Clipboard Function Summary 
Table 17-2 summarizes the clipboard functions. The detailed function descriptions are in the next section. 


ChangeClipboardChain . 
CloseClipboard 


CountClioboardFormats 
EmptyClipboard 
EnumClipboardFormats 
GetClipboardData 
GetClipboardFormatName 
GetClipboardOwner 
GetClipboardViewer 
GetOpenClipboardWindow 
GetPriorityClipboardFormat 
 {sClipboardFormatAvailable 
OpenClipboard 
RegisterClipboardFormat 
SetClipboardData 


SetClipboardViewer 


Removes a clipboard viewer program from the chain of viewer programs. 
Closes the clipboard after it was opened either to add data, or to read data. 
Determines the number of clipboard formats currently in use. 

Empties the clipboard and frees the data associated with it. 

Lists all of the formats available in the clipboard. 

Retrieves a handle to the data in the clipboard. 

Determines the name of a special clipboard format. 

Retrieves the handle of the application that owns the clipboard. 

Retrieves the handle of the first clipboard viewer in the clipboard viewer chain. 
Determines the handle of the window that most recently opened the clipboard. 
Checks the clipboard for availability of desired data formats. | _ 
Checks whether the clipboard contains data in a specific format.- 

Opens the clipboard so that an application can read or set the contents. 
Registers a new clipboard format name with Windows. 


Passes a global memory handle to the clipboard. The memory block becomes the clipboard 
data. 


Adds a new window to the list of windows in the clipboard viewer chain. 


Table 17-2. Clipboard Function Summary. 


Clipboard Function Descriptions 
This section contains the detailed descriptions of the clipboard function. 


mw Win 3.0 


CHANGECLIPBOARDCHAIN Win 2.0 w Win 3.1 

Purpose Removes a clipboard viewer program from the chain of viewer programs. 

‘Syntax BOOL ChangeClipboardChain(HWND hWnd, HWND hWndNezt), 

Description This function is useful only if SetClipboardViewer() has been called to install a clipboard viewer. 
Clipboard viewers receive WM_DRAWCLIPBOARD messages, and are expected to display the 
data currently in the clipboard. 

Uses . Used when an application is removed from the clipboard viewing chain. : 

‘Returns BOOL. TRUE if hWnd was removed from the clipboard viewer chain, FALSE on error: 

See Also SetClipboardViewer() 

Parameters . : 

hWnd HWND: The window handle of the window to be removed from the clipboard viewer chain. This 
handle must have been previously passed to Windows by SetClipboardViewer(). 

hWndNext HWND: The window handle of the window that follows hWnd in the chain of clipboard viewers. 


This value is returned by SetClipboardViewer(), and should be saved in a static variable. 
‘Related Messages WM_DRAWCLIPBOARD, WM_CHANGECBCHAIN 
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Example This example creates a clipboard viewer. The application will display the current contents of the 
- . Clipboard if the clipboard contains either the CF_TEXT or CF_BITMAP data type. Clicking the . 
“Do It!” menu item empties the clipboard. The viewer installs itself in the clipboard viewer chain 
when the application starts, and removes itself from the chain on exit. 


one FAR PASCAL uaaRéac CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ; ps ; 

HDC ' hMem0C ; 

HBITMAP hBitmap ; 

BITMAP bm ; 

RECT rClientRect ; 

HANDLE hMem ;° 

LPSTR LpMem ; 

static : HWND hNextViewer ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_CREATE: 

hNextViewer = SetClipboardViewer (hWnd) ; 
break ; 

* case WM_ PAINT: 
BeginPaint chund, eeyes 
GetClientRect (hWnd, @rClientRect) ; 

. OpenClipboard (hWnd) -; 

if ChMem = GaLclphoeraDace CCF_TEXT)) 


{ 
LpMem = GlobalLock (hMem) ; 
" DrawText (ps.hdc, LpMem, -1, &rClientRect, 
DT_LEFT) ; 
GlobalUnlock (hMem) ; 
} i 


..else if ChBitmap = GetClLipboardData (CF_BITMAP)) 
{ 


hMemDC = CreateCompatibleDC (ps.hde) ; 
SelectObject (hMemDC, hBitmap) ; 
GetObject (hBitmap, sizeof (BITMAP), 
CLPSTR) &bm) =; 
BitBlt (ps. hde, 0, Q, bn. bmWidth, bm. bmHeight, 
hMempC, 0, 0, SRCCOPY) 
DeleteDC ChMembc) ; - 
} 
CloseClipboard () ; 
EndPaint (hWnd, &ps) ; 
break ; 
case WM_DRAWCLIPBOARD:. 
if ChNextViewer) 
SendMessage ChNextViewer, ve _DRAWCLIPBOARD, 
‘wParam, lParam) ; : 
InvalidateRect Chwnd, NULL, TRUE) ; /* force paint */ 
break ; 
case WM_ CHANGECBCHAIN: 
if (wParam == hNextViewer) 
hNextViewer = LOWORD (lParam) ; 
else if (hNextViewer) 
SendMessage (hNextViewer, WM_CHANGECBCHAIN, 
wParam, lParam) ; 
break ; 
case WM_ COMMAND: /* process menu items */ 
switch (wParam) 
: 4 
case TDM DOIT: /* empty the eUipboard */ 
OpenClipboard nena? i 
EmptyClipboard () ; 
CloseClipboard () ; |. 
InvalidateRect Chad, NULL, TRUE) ; 
break ; 
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case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; ye 
case WM_DESTROY: /* stop application */ 
ChangeClLipboardChain ChWnd, hNextViewer): ; 
PostQuitMessage (0) ; 
break ; be. ga. 
default: /* default windows message processing */ 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; 


} 

CLOSECLIPBOARD mWin2.0 wmWin3.0 wm Win3.1 

Purpose Closes the clipboard after it was opened either to add data or to read data. 

Syntax BOOL CloseClipboard(void); | 

Description The clipboard is a global memory block which has been passed to Windows from an ‘silicailon 
OpenClipboard() makes the data temporarily available to an application. CloseClipboard() re- 
turns control of the memory block to Windows. 

Uses Used after OpenClipboard() to return control of the clipboard data to Windows. Control should 
not be passed to Windows while the clipboard is open. Open and close the clipboard while pro- 
cessing a single Windows message. 

Returns BOOL. TRUE if the clipboard was closed, FALSE on error. 

See Also OpenClipboard(), EmptyClipboard() 

Parameters None (void). 

Example See the previous example under ChangeClipboardChain() and the example under SetClip- 

boardData(). 

CounTCLIPBOARDFORMATS mWin2.0 mWin30 mWin3.1— 

Purpose Determines the number of clipboard formats curren!ty in use. __ 

Syntax int CountClipboardFormats(void); 

Description Some applications put more than one format of data in the clipboard. This allows a variety of 
applications to read the data, even if they do not support all of the formats available. 

Uses Determines if more than one clipboard format is available. EnumClipboardFormats() can then 
be used to determine which formats are available. 

Returns int, the number of data formats currently in the clipboard. 

See Also EnumClipboardFormats(), GetClipboardFormatName() 

- Parameters None (void). 

Example See the example under EnumClipboardFormats(). 

EMPTYCLIPBOARD . wWin20 mWin30 mWin3.1 

Purpose Empties the clipboard and frees the data associated with it. 

Syntax - BOOL EmptyClipboard(void); 

Description This function is used to remove data from the dipteard It is éailed after OpenClipboard(), and 


before CloseClipboard(). Any global memory that was associated with the clipboard by an appli- 
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Example 


- available clipboard formats after. . 


cation calling SetClipboardData() i is freed. The window calling EmptyClipboard() becomes the 
current clipboard owner. 


Uses Use this prior to calling SetClipboardData() to make sure that the clipboard is empty. Also used 
to empty the clipboard so that no data is visible in an open clipboard viewer. 
Returns BOOL. TRUE if the clipboard was emptied, FALSE on error. 
See Also OpenClipboard(), CloseClipboard() 
Parameters None (void). . - 
Related Messages WM_DRAWCLIPBOARD, WM_CHANGECBCHAIN 
Example See the examples under ChangeClipboardChain() and SetClipboardData(). 
ENUMCLIPBOARDFORMATS | - mWin2.0 mWin3.0 mWin3.l 
Purpose Lists all of the formats available in the clipboard. . 
Syntax WORD EnumClipboardFormats(WORD wFormat); 
Description The clipboard can contain data that uses any of the predefined clipboard formats (listed under 
SetClipboardData()) or a special clipboard format made with RegisterClipboardFormat(). 
EnumClipboardFormats() is called repeatedly to determine all of the formats. On the first 
‘call, wFormat is set to zero. EnumClipboardFormats() returns the first format available. On the 
second and subsequent calls, the last format returned is used for wFormat in the next call. This 
sequence is repeated until the funetion returns ze, specifying that the nal format has been 
read. 

Enum ChipboardFormatad) lists all of the formats that are currently in use in the clipboard. In. 
most cases, this will be a single format. Some applications set more than one version of the data 
to the clipboard, so that other applications can read the data if they only support a few formats. 

EnumClipboardFormats() lists the formats in the same order that the application that set 
the clipboard used in loading the data. The first format enumerated should be the most desirable 
(Jeast data lost). For example, a DIB (device-independent bitmap) would be preferable to a DDB 
bitmap. 

Uses “Used with applications that support more than one means of reading the ciphoant Ranmerating 
the clipboard allows the application to choose which format to use in reading the data. 
Returns WORD, the next known clipboard format number. Returns zero if the last format was read. 
* See Also’ _ CountClipboardFormats, GetClipboardFormatName() 
“Parameters: . ; . 
wFormat WORD: The format number of the last format read. Set to zero for the first call to EnumClip- 
boardFormats(). Set to the last value returned by the function for‘all subsequent calls. 
This example lists all of the clipboard formats available when the user clicks the “Do It!” menu 


item. For custom formats (set by applications which call RegisterClipboardFormat()), the name. 
of the format can be retrieved using GetClipboardFormatName(). For predefined clipboard for- 
mats, the names are not returned by \ 

GetClipboardFormatName(). The 
listing includes a function called 


eee Baim 


Dott! Qu | 
teeth iid es ‘Rich Text Format. (0xd2cd) clipboard format available 
the names of the'predefined for- | ce _oWNERDISPLAY. (0x80 ) clipboard format available. 


mats. CF_TEXT, ( 0x1 ) clipboard format available. 


Figure 17-2 ‘shows the list of Link, ( Oxdief) clipboard format avallable. 
CF_OEMTEXT. ( 0x? ) clipboard format available. 


Microsoft Word for Windows has. - Figure 17-2: EnumClipboardFormats(. ) Example. 
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~. been used to copy text to the clipboard (Edit/Copy menu item). This application supplies the 


clipboard with five clipboard formats. An application reading or viewing the clipboard could use 
any of these to obtain the text copied. 

EnumClipboardFormats() retrieves the formats in the same order that data was added into 
the clipboard, which should be the priority order. In this case, the most desirable format is a 
special format called “Rich Text Format.” The next most desirable is the CF_OWNERDISPLAY 
predefined format, which is only suitable for a clipboard viewer. Next is the CF_TEXT format, 
which includes the text characters, but omits formatting characters. Next is a special format 
called “Link.” The last, and least desirable format, is CP_OEMTEXT which will only have the OEM 
character set. As you can see, Word for Windows goes to a lot of trouble to make the data in the 
clipboard useful. 


~ 


void NameClipFormat (int nFormat, char *cName) ; 


{ 


HDC 
int 
char 


Long FAR PASCAL WndProc (CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


hDC.; 
i, n, nCBFormats, nFormat ; 
cBuf £128], cName C64] ; 


switch CiMessage) ‘ /* process windows messages */ 


} 


case WM_COMMAND: . _ 1* process menu items */ 
switch (wParam) . 


case IDM_DOIT: | . /* User hit the “Do it" menu item */ 
hDC = GetDC ChWnd) ; 
nCBFormats = CountClipboardFormats() ; 
OpenClipboard (hWnd) ; 
nFormat = 0 ; 
for (i = 0 ; i < nCBFormats ; i++) 
{ . \ 
nFormat = EnumClipboardFormats , 
CnFormat) ; 
-n = GetClipboardFormatName (nFormat, 
cName,, 63) ; 
if (n == 0) 
NameClipFormat (nformat, cName) ; 
TextOut Chac, 10, i * 20, cBuf, 
wscrintf CcBuf, 
“4s, © Ox%x ) clipboard format available."”, 
CLPSTR) cName, nFormat)) ; 
} 
CloséeClipboard () ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 


, 


} 
break ; 

case WM_DESTROY: 
PostQuitMessage (0) ; 
break ; 

default: : 

return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


return (COL) ; 


/* fills jn cName with the name of a predefined clipboard format */ 


void NameClipFormat Cint nFormat, char *cName) 


{ 


static char *cClipName C91 = {"CF_TEXT", “CF_BITMAP", 


“CFLMETAFILEPICT", "“CF_SYLK", "CF_DIF", “CFLTLFF", 
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“CFLOEMTEXT", “CF_DIB", "CF_PALETTE" } ; 


static char *cClipName2 C4] = {"CF_OWNERDISPLAY", 


“CF_DSPTEXT", "CF_DSPBITMAP", “CF_DISPMETAFILEPICT"} ; 


if (nFormat <= 9) 


-strepy (cName, cClipName EnFormat - CF_ TEXT]) ; 


else if (nFormat <= 0x83) 


“strepy (cName, cCLipName2 EnFormat ~ CF _OWNERDISPLAY]) ; 


else 
: “strepy (cName, "<Not named>"> s 

GeciiesomeDMA _ mWin2.0 mWin30 Wind] 

Purpose ’ Retrieves a handle to the data in the clipboard. 

Syntax HANDLE GetClipboardData(WORD wFormat); 

Description This function checks the clipboard to see if the clipboard holds the specified data foriial If so, a 
handle to the clipboard memory block is returned. This function is called after OpenClipboard(), 
and before CloseClipboard(). The application should copy the memory block immediately after re- 
ceiving the handle. Otherwise, another application may empty the clipboard, invalidating the handle. 

Uses . Retrieving data from the clipboard. 

Returns HANDLE, a handle to a global memory block. NULL on error. Lock the memory block with 
GlobalLock() before reading the data, and unlock it with GlobalUnlock() as soon as the data is read. 

See Also OpenClipboard(), CloseClipboard(), SetClipboardData() | 

Parameters oe 

wFormat WORD: Specifies what type of data the application would like to read from the clipboard memory 


block. The format can be any of the ones listed in Table 17-3. 


CF_BITMAP 


A bitmap handle (HBITMAP). 


CF_DIB ~ Amemory block containing a device-independent bitmap (DIB). The block will contain a 
BITMAPINFO data structure followed by the bitmap bits. 
CF_DIF ~ Software Arts’ Data Interchange Format. 
CF_DISPBITMAP A private bitmap display format. 
CF_DSPMETAFILEPICT A private metafile display format. 
CF_DISPTEXT A private text display format. 
CF_METAFILEPICT A metafile picture. The memory block will contain a METAFILEPICT data structure. 
CF_OEMTEXT A memory block containing only OEM text characters. Each line ends with a CR-LF pair. A 
NULL byte marks the end of the text. .This is the format Windows uses to transfer data between 
non-Windows and Windows applications. 
CF_OWNERDISPLAY The clioboard owner is responsible for painting the clipboard. The clipboard owner should 
process WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, 
WM_SIZECLIPBOARD, and WM_VSCROLLCLIPBOARD messages. 
CF_PALETTE - Ahandle to a color palette. 
CF_SYLK Microsoft Symbolic Link (SYLK) format. 
CF_TEXT A memory block containing text characters. Each line ends with a CR-LF pair. A NULL byte 
"marks the end of the text, This is the standard format for excenond text between Windows 
applications. ed ea 
CF_TIFF 


Tag Image File Format. 


Table 17-3. Clipboard Data Formats. 
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In addition, private clipboard formats can have values between CF_PRIVATEFIRST and 
CF_PRIVATELAST. 


Related Messages WM_ASKCBFORMATNAME, WM_ HSCROLLCLIPBOARD, WM_PAINTCLIPBOARD, WM_SIZE- 


CLIPBOARD, WM_VSCROLLCLIPBOARD 


Caution The application calling GetClipboardData() should unlock the memory block as soon as it is read. 
Leaving the clipboard memory block locked while Windows processes messages may cause the 
system to crash. 

Example See the examples under the ChangeClipboardChain() and SetClipboardData() function 
descriptions. 

GETCLIPBOARDFORMATNAME mWin2.0 mWin3.0 mWin3l 

Purpose Determines the name of a special clipboard format. 

Syntax int GetClipboardFormatName(WORD wFormat, LPSTR [pFormatName, int nMaxCount); 

Description Applications can use RegisterClipboardFormat() to store data in the clipboard under a special 
format name. GetClipboardFormatName() allows other applications to check the name(s) of the 
clipboard formats available to see if the data in the clipboard is in the right format to use. Names 
of predefined clipboard formats are not returned. 

The special format name does not imply that the data is coded. The data can be ina standard 
format such as CF_TEXT. The format name simply gives the clipboard data special meaning. For - 
example, a spreadsheet might cut and paste using the clipboard with a special format registered 

as “SPREADSHEET.” The actual data passed to the clipboard could be the characters in the 
spreadsheet cell plus formatting characters. 

Uses Used with EnumClipboardFormats() to find the names of the formats available. Only special 
formats registered with RegisterClipboardFormat() have stored names. The standard formats 
(listed under SetClipboardData()) will not return a name. 

Returns int, the number of characters read. Zero on error. CREE - , 

"See Also. EnumClipboardFormats(), RegisterClipboirdFormat() s— generic [~[~ 
Parameters y Do lt! Quit 
wFormat WORD: The format number. This is a format number returned 
by EnumClipboardFormats() or RegisterClipboardFormat(). Owner: Snap3: . 

lpFormatName — LPSTR: A pointer to a memory buffer that will hold the name Viewer: Clipboard 

of the clipboard format. The buffer should be at least 
ae nMaxCount bytes wide. » : Figure 17-3, GetClip- 

nMaxCount int: The maximum sing size to be read into the lpFormat-° boardOu:ner() and GetClip- 
Name buffer. If the clipboard format name is longer, it willbe boardViewer() Example. 
truncated, . i, 

Example See the example under EnumClipboardFormats(). 

GETCLIPBOARDOWNER meWin2.0 mWin3.0 mWin3.1 

Purpose Retrieves the handle of the application that owns the clipboard. 

Syntax HWND GetClipboardOwner(void); 

Description The clipboard owner is the last application to call SetClipboardDataQ). This function returns that 

~ application’s handle. 

Returns HWND, the handle of the application that owns the clipboard. NULL if the ee is currently 


unowned. 
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See Also GetClipboardViewer() 

Parameters None (void). 

Example _ This example displays the current clipboard viewer and owner.window names. (See Figure 17-3.) 
The names are updated when the user clicks the “Do It!” menu item, or when the window i is 
painted for any reason. 


Long FAR PASCAL WndProc CHWND hwnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 
PAINTSTRUCT 


ps ; 
HWND hCBOwner, hCBViewer ; 
char. ; cBuf C128], cName £64] ; 


switch (iMessage) 


case WM_PAINT: 
BeginPaint ChWnd, gps) ; ; 
hCBOwner = GetClipboardOwner ©) ; 
if (hCBOwner == NULL) 
: Lstrcpy (cName, "<None>") ; 
else ; 
GetWindowText (hCBOwner, cName, 63) ; 
TextOut (ps.hde, 10, 10, cBuf, wsprintf (cBuf, 
"Owner: %s'', CLPSTR) cName)) ; ; 
hCBViewer = GetClipboardViewer () ;: 
if ChCBViewer == NULL) 
. istrepy (cName, '<None>") ; 
else ae ie 
GetWindowText ChCBViewer, cName, 63) ; 
TextOut (ps.hdc, 10, 30, cBuf, Me BET Gee CcBuf, 
"Viewer: 4s", CLPSTR) cName)) ; 
EndPaint ChWnd, &ps) ; 
. break ; ~ ‘ 
case WM_' COMMAND: : : 
switch (wParam) 
{ " 


case IDM_DOIT: 
envet tdatenect ChWnd, NULL, TRUE) ; 


a break ; 
[Other program lines] ee 
GETCLIPBOARDVIEWER | | mWin20  mWind 0 mWin3. 
Purpose '. _. Retrieves the handle of the first clipboard viewer in the clipboard viewer chain. 
Syntax ~~” HWND GetClipboardViewer(void); 
Description | The standard clipboard viewer application is supplied with Windows, This is the Clipboard appli-. 


cation that Windows installs in the Main group. Other applications can be added to the a pias 
_ viewer chain. See ChangeClipboardChain() for an example. 


Returns HWND, the handle of the first window in the clipboard viewer chain. NULL if a eiphonrl viewer 
’ is not running. — 4 

See Also GetClipboardOwner() 

Parameters | None (void). 

Example See the previous example under the GetClipboardOwner() function description 

GrTOrenCLiPsoaRpDWinpow 7 ; wWin20 wWin3.0 mWin3.1 

Purpose. Determines the handle of the window that most recently opened the elnhonts 


Syntax HWND GetOpenClipboard Window (void); 
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Description The clipboard is a shared resource. Only one application can have the clipboard open for reading 
and writing data at any one time. This function returns the window handle of the application that 
currently has the clipboard open. 


Returns : HWND, the window handle of the window which sitisaly has the clipboard open. If the clip- 
board is not open, the function re- ', 
turns NULL. —- generic |, [wf 
See Also GetClipboardOwner(), GetClip- Do It! Quit 
- . boardViewer(), OpenClipboard() Clipboard Owner = Snap3 
armmeters: «None (nia) _ Iclipboard Viewer = Clipboard Viewer 
Example This example, as shown in Figure i 


Opened Clipboard = Clipboard Viewer 


17-4, displays the current clipboard 
owner, viewer, and the window — 

‘which most recently opened the Figure 17-4. GetOpenClipboardWindow() Example. 
clipboard. The owner is the applica- 
tion that placed the current data into the clipboard. In this case, SNAP3.EXE placed data in the 
clipboard. The standard Windows clipboard viewer application was then activated, which be- 
comes both the clipboard viewer and the application that most recently opened the clipboard. 


-Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


PAINTSTRUCT ps ; 

char cBuf £128], cWindName (64) ; 

HWND hClipWind ; 

switch CiMessage) /* process windows messages */ 
{ 


case WM_PAINT: 
BeginPaint Chwnd, &ps) ; 
hClipWind = GetClipboardOwner O; : 
GetWindowText ChClipWind, ewindNeme:, 63) ; 
TextOut (ps.hdc, 0, 0, cBuf, wsprintf (cBuf, 
‘“Clipboard Owner = Zs", CLPSTR) cWindName)) ; 
hClLipWind = GetClipboardViewer () ; 
GetWindowText (hClipWind, cus Hanae 63) ; 
TextOut (ps.hdc, 0, 20, cBuf, wsprintf (cBuf, 
“Clipboard Viewer = %s", (LPSTR) cWindName) ) 

hClipWind = GetOpenClipboardWindow () ; 
GetWindowText (hCLipWind, cWindName, 63) ; 
TextOut (ps.hdc, 0, 40, cBuf, wsprintf (cBuf, 

; “Opened Clipboard = %s", (LPSTR) cWindName) ) 
EndPaint (hWnd, &ps) ; 


Ne 


™e 


break ; 
case WM_CHANGECBCHAIN: /* Chiebaard view chain changed */ 
inyel peareRect ChWnd, erty TRUE) ; /* force paint */ 
break ; : . 
case WM_ COMMAND: ; /* process menu items */ 


switch (wParam) 
{ 


case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: 
Postauictessage (0) ; 
break ; 
default: 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} tae 
return (OL) ; 
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is read via standard clipboard proto- 


GerPriontTyCLirsOARDFORMAT_ mm Win2.0 mm Win8.0 Win 3. 

Purpose - Checks the clipboard for the availability of desired data formats. - 

Syntax int GetPriorityClipboardFormat(WORD FAR *IpPriorityList, int County 

. Description | —_— Applications can support more than one data format for exchanging data to and from the clip- 

‘ board. There can be more than one predefined format (see SetClipboardData() for a list), and 
more than one custom clipboard format (see RegisterClipboardFormat()). Generally, some data 
formats will be better than others for exchanging data. GetPriorityClipboardFormat() allows the 
clipboard to be scanned using a list of formats. The first format from the /pPriorityList that is 
available on the clipboard is returned by the function. This will be the best format for the applica- 
tion to read in data from the clipboard using GetClipboardData(). : 

Uses Generally used with applications that use eapectal clipboard formats, registered with . 

__ RegisterClipboardFormat(). 
Returns int, the highest priority clipboard format aaliable® If the clipboard is empty, the function returns 
. NULL. Ifthe clipboard contains data, but not in any of the desired formats, the function returns -1. 

See Also RegisterClipboardFormat(), IsClipboardFormatAvailable(), EnumClipboardFormats() 

Parameters af + ae. 

lpPriorityList ~ WORD FAR *: A pointer to an array of word values. Each element of the array should contain the 
number of a desired clipboard format. This is either one of the predefined formats such as 
CF_TEXT, or a special format returned by either RegisterClipboardFormat() or, Enum(Clip- 
boardFormats(). The list should be in priority order, with the most desirable formats first. - 

nCount int: The number of elements in the array pointed to by /pPriorityList. 

Example - This example demonstrates several advanced uses of the clipboard. When the application is 


started (WM_CREATE message is processed), a special clipboard format is registered. In addi- 
tion, the clipboard is set for delayed rendering of two clipboard formats, CF_TEXT and the spe- 
cial format. With delayed rendering, data is not loaded into the clipboard unless an application 
requests it. In this case,Windows sends the WM _RENDERFORMAT message. The application 
then loads the data into the clip- . 

Se a generic ee 2 [eT 


board. When a WM_PAINT message 


is received, the application reads 
the clipboard. Both clipboard for- — - 
CF_TEXT contains: Special data in clipboard 
Special CB Format contains: Special data in ¢ts.coard 


mats are read. The CF_TEXT format 


col. Before reading the special clip- Figure 17-5. GetPriorityClipboardFormat() Example. 
board format, the application uses 

GetPriority ClipboardFormat() to check which formats are available. In this case, a list of only 
two desired formats is checked. If the special format is available, the contents of the clipboard 
are displayed on the application’s client area, as shown in Figure 17-5. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, Si eee LONG lParam) 


PAINTSTRUCT ps ; ee 

HANDLE hMem, hMem2, hCdipMem ; 

LPSTR lpStr, Lpctip ; 7 

char cBuf [128] ; 

static WORD wClipFormat ; 

WORD wPriorityList C2] ; 

switch CiMessage) a . ag .. /* process windows messages */ 


case WM_CREATE: 
wClipFormat = RegisterClipboardFermat 
C"SPECIAL") ; 


NX 
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OpenClipboard (hWnd) ; /* set clipboard for delayed */ 
EmptyClipboard () ; /* rendering of CF_TEXT */ 
SetClipboardData (CF_TEXT, 0) ; 
if (wClipFormat) 
SetClipboardData (wClipFormat, 0) ; 
_CloseCtipboard () ; 
break ; .. 
case WM_RENDERALLFORMATS: aa ; 
case WM_RENDERFORMAT: /* now put data in clipboard */ 
OpenClipboard (hWnd) ; 
EmptyClipboard () ; 
hMem = GlobalAlloc (GHND, 64) ; 
_UpStr = GlobatLock ChMem) ; 
Lstrcpy (lpStr, "Text In Clipboard") ; 
GlobalUnlock (ChMem) ; 
SetClipboardData (CF_TEXT, hMem) ; 
if (wClipFormat) 


{ 
hMem2 = GlobalAlloc (GHND, 64) ; 
tpStr = GlobalLock ChMem2) ; 
Lstrcepy (lpStr, “Special data in clipboard”) ; 
GlobalUnlock (hMem2) ; 
SetClipboardData (wClipFormat, hMem2) ; 
} 
CloseClipboard () ; 
break ; 


case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
'OpenClipboard (hWnd) ; 
hClipMem = GetClipboardData (CF_TEXT) ; 
if ChClipMem) 
€ 4 


lpClip = GlobalLock (hCLipMem) ; 

TextOut (ps.hde, 10, 10, cBuf, wsprintf (cBuf, 
“CF_TEXT contains: %s", LpClip)) ; 

GlobalUnlock ChClipMem) ; — 


s 3} : 
CloseClipboard () ; 


OpenClipboard ChwWnd) ; 

wPriorityList CO] = wCtipFormat ; 

wPriorityList Ci] = CF_TEXT ; 

if (wClipFormat = , 
GetPriorityClipboardFormat (wPriorityList, 2)) 


{ 
hClipMem = GetClipboardData (wClipFormat) ; 
LpClip = GlobalLock (hClipMem) ; 
TextOut (ps.hdc, 10, 30, cBuf, wsprintf (cBuf, 
“Special CB Format contains: %s", LpClip)) ; 
GlobalUnLlock ChClipMem) ; 
} 


CloseClipboard () ; 

ene ants ChWnd, aps) ; ; 

break ; . 

case WM_ COMMAND: 

switch (wParam) 

{ 

case IDM_DOIT:. . 

InvalidateRect ChWnd, NULL, TRUE) ; 

: break ; 

case IDM_QUIT: 

DestroyWindow ChWnd) ; 


break ; 
} 
break ; : is . ; 
case WM_DESTROY: “*® stop application */ 
Postauittessage (0) ; ‘ ot 
break ; gh 
default: /* default windows message processing */ 
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return DefWindowProc (hWnd, iMessage, wParam, lParam) : 


} 
return (QOL) ; 


} 

IsCLIPBOARDFORMATAVAILABLE , Win 2. 0 mWin30 mg Win3.1 

Purpose Checks whether the clipboard contains data in a specific format. 

Syntax BOOL IsClipboardF ormatAvailable(WORD wFormat); ; 

Description _ The clipboard can contain data in any of the predefined data formats (see SetClipboardData() 
for a list), or in a special format set with RegisterClipboardFormat(). IsClipboardFormat- 
Available() checks to see if one specific data format is currently loaded on the clipboard. 

Uses Tnis function is appropriate if only one data format is being read. If the application can use 

; several formats, use GetPriorityClipboardFormat() instead. 

Returns BOOL. TRUE if data of the specified format is available in the clipboard, FALSE if not. 

See Also GetPriorityClipboardFormat(), Een ibeerdorats0) 

Parameters 

wFormat WORD: The desired clipboard format. This is s either one of the predefined formats, or a special 

2 format registered by an application with RegisterClipboardFormat() 
Example This example registers a special 


clipboard format called “SPECIAL” 
when the WM_CREATE message is 


= | generic | Ge ae 


Do It! Quit : ? 
delayed rendering ofthe data, This 
means that the actual data is not - Figure 17-6. IsClipboardFormatAvailable() Example. 
loaded into the clipboard unless ei- 
ther a WM_RENDERFORMAT or WM _RENDERALLFORMATS message is received. When a 
WM_PAINT message is processed, the application checks whether data in the “SPECIAL” format 
is available in the clipboard. If so, the data (as a‘character string) is displayed on the application’s 
client area, as shown in Figure 17-6. If not, nothing is displayed. 


Long FAR PASCAL WndProc CHWND pune x unsigned Message, WORD WPar aus LONG lParam) 
C 


PAINTSTRUCT | “Ds a 


HANDLE ! - hMem,: hClipMem ; 

LPSTR : lpStr, lpClip ; 

char cBuf £128] ; 

static. . - WORD - wClipFormat ; 

| ‘ : ’ 
Iswitch (iMessage) /* process windows messages */ 


{ 
; case WM_CREATE: 
: wClipFormat = RegisterClipboardFormat 


ry C"SPECIAL") ; 
OpenClipboard chlind) ; /* set clipboard for detaved */ 
EmptyClipboard () ; i rendering */ 


SetClipboardData Cucliprormat, Ome 
Ctosebttphoard ©); 
break ; 
case WM_ RENDERALLFORMATS: ‘ ; 
case WM_RENDERFORMAT: _/* now put data in clipboard */ 
OpenClipboard (hWnd) ; : ya 
EmptyClipboard () ; 
hMem = GlobalAlloc (GHND, ORs 
_UpStr = GlobalLock ChMem) ; 2 
istrepy (lpStr, “Special ata in clipboard”) ; ae 
SetClipboardData (wClipFormat, hMem) ; 
_GlobalUnlock ChMem) ; 
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Eloseé Eippoatd QO; 
break ; 
case WM_PAINT: 
BeginPaint ChWnd, REDS) os 
OpenCLipboard (hWnd) ; 
if (IsCLipboardFormatAvai lable CwClipFormat)) 


{ 
hClipMem = GetClipboardData (wClipFormat) ; 
hMem = GlobalAlloc (GHND, Globatsize Chel ipMen)) ; 
UpStr = GlobalLock (hMem) ; 
LpClip = GlobalLock Chetipfem) ; 
Lstrcpy (lpStr, tpClip) ; 
TextOut (ps.hde, 10, 10, “cBuf, wsprintf (cBuf, 
. “Special CB Format contains: %s", lpStr)) ; 
GlobalUnlock (hMem) ; 
GlobalFree (hMem) ; 
GlobalUnlock (hClipMem) ; 
} 


CloseClipboard () ; 

EndPaint ChWnd, &ps) ; 

break ;. 

case WM_COMMAND: 

switch (wParam) 

{ 

case IDM_DOIT: 
InvalidateReet ChWnd, NULL, TRUE) ; 
break ; 

case IDM_QUIT: 
Destroywindow ChWnd) ; 


uf 


break ; 
} 
break ; 
case WM_| DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; : 
default: /* default windows message processing */ 
“return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} : 
return (OL) ; 

} 

OpENCLIPBOARD 8 mWin2.0 mWin30 mWin3.1- 

Purpose > Opens the clipboard so that.an application can read or set the contents. 

Syntax BOOL OpenClipboard(HWND hWnd); 

Description The clipboard is a global memory block maintained by Windows. OpenClipboard() makes the 
memory block available to the application. GetClipboardData() can then be used to read the data 
in the memory block, and SetClipboardData() can be used to give the clipboard a new memory 
block. The clipboard remains open to the application until CloseClipboard() is called. The appli- 
cation should not relinquish control to Windows while the clipboard is open. The clipboard should 
be opened and closed while the application processes one Windows message. 

Uses Used prior to GetClipboardData() and SetClipboardData(). OpenClipboard() works by changing 
the memory attributes of the block of memory that the clipboard is currently referencing. 

Returns BOOL. TRUE if the clipboard is opened, FALSE on error (for example, if another application has 

left the clipboard open). 

See Also — GlosecMpboardQ), GetClipboardDataQ), ere nea 

Parameters 

hWnd HWND: The handle of the window that is opening the clipboard. » 

Example _See the examples under ChangeClipboardC hain) and SetClipboardData(). 
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REGISTERCLIPBOARDFORMAT : mWin2.0) mWin3.0) mg Win3l 
Purpose Registers a new clipboard format name with Windows. 
Syntax WORD RegisterClipboardFormat(LPSTR lpFormatName); 
Description Applications can use special clipboard format names to pass data to and from the clipboard. For 
example, a spreadsheet may want to cut and paste cell contents using a format called “SPREAD- 
_ SHEET.” Using a special format name prevents other applications from attempting to read data 
that will not be correctly interpreted. Applications can simultaneously load more than one data 
format to the clipboard. By doing so, data is made available to many other applications which-may 
differ in their abilities to read different formats. For example, the spreadsheet could put the 
‘ complete cell data in the clipboard under the special “SPREADSHEET” format, and put the text 
contents of the cell using the standard CF_TEXT format. 
Uses Used with applications that need to transfer data using specialized formats. 
_ Returns WORD, the format number. NULL on error. The format number will Oe between 0xC000 and 
OxFFFF. 
See Also EnumClipboardFormats(), setclihoaaneraataakd 
- Parameters . : . 
lpFormatName _ LPSTR: A pointer to a null-terminated character string containing the new format name. 
Example See the examples under IsClipboardFormatAvailable() and GetPriorityClipboardFormat(). 
SETCLIPBOARDDATA : | eWin2.0 mWin3.0 mWin3.i 
Purpose Passes a global memory handle to the clipboard. The memory block becomes the clipboard data. - 
Syntax HANDLE SetClipboardData(WORD wFormat, HANDLE hMem), 
Description The clipboard consists of a global memory block that has been registered in Windows as belong- 
, ing to the clipboard. SetClipboardData() registers the memory block with Windows. When the 
block of memory has been registered, applications should not free the data or leave the block 
locked. The memory block should be considered to be owned by the clipboard. Applications using 
the clipboard should not allow control to pass to Windows while the clipboard is open. In other 
words, the clipboard should be opened and closed while processing one Windows message. 
Uses -:. _ This is the only way to set the clipboard data. Prior to calling this function, the application should 
- call OpenClipboard() and EmptyClipboard(). As soon as the memory block is passed to the clip- 
board with SetClipboardData(), CloseClipboard() should be called and the memory block un- . 
. locked (if it has been locked). 
Returns HANDLE, a handle to the data in the clipboard. This value is normally not used. 
See Also OpenClipboard(), GetClipboardData(), EmptyClipboard(), CloseClipboard() 
Parameters 
wFormat ie * WORD: Specifies what type of data the memory block eierencsd by hMem contains. The data 


type can be any of the those listed in Table M- 4, 


CF_BITMAP 
CF_DIB 


CF_DIF 


CF_DISPBITMAP 


A Siieai handle le HBITMAP). 


A memory block containing a device- independent bitmap (DIB). The block will contain a 
BITMAPINFO data structure followed by the bitmap bits. 


Software Arts’ Data Interchange Format. 
A private bitmap display format. . 


CF_DSPMETAFILEPICT _ Aprivate metafile display format. 
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A private text display format, | . 


CF_DISPTEXT 
~ CF_METAFILEPICT A metafile picture. The memory block will contain a METAFILEPICT data structure. 
CF_OEMTEXT A memory block containing only OEM text characters. Each line ends with a CR-LF pair. A 
NULL byte marks the end of the text. This is the format Windows uses to transfer data between 
non-Windows and Windows applications. 
CF_OWNERDISPLAY ~ The clipboard owner is responsible for painting the clipboard. The clipboard owner ‘should 
process WM_ASKCBFORMATNAME, WM_HSCROLLCLIPBOARD, WM_] PANG rE OAnD: 
‘WM_SIZECLIPBOARD, and WM_VSCROLLCLIPBOARD messages. 
CF_PALETTE A handle to a color palette. 
CF_SYLK Microsoft Symbolic Link (SYLK) format. 
UF_TEXT A memory block containing text characters. Each line ends with a CR-LF pair. A NULL byte 
marks the end of the text. This is the standard format for exchanging text between Windows 
: applications. 
CF_TIFE Tag Image File Format. 


_ ‘Table 17-4. Clipboard Data Formats. 


hiem 


Related Messages 
Example 


In addition, private clipboard formats can have values between CF_PRIVATEFIRST and CF_PRI- 
VATELAST. 


HANDLE: A handle to a global memory block that contains the data in the specified format. For 
delayed rendering of the clipboard, set hMem to NULL. This means that the data does not have to 
be passed to the clipboard until a WM_RENDERFORMAT message is received. 


.WM_RENDERFORMAT, WM_RENDERALLFORMATS 


This example shows the workings of a screen capture program called SNAP3. When the user 
clicks the “Start Capture” menu item, the mouse changes to a cross hair shape. If the user de- 
presses the left mouse button and drags the mouse, a rectangle appears on the screen. Dragging 
the mouse increases the size of the- - 
rectangle. When the mouse button [iam fan et ot gf kbs 
is released, the area bounded by the Start Capture Glear Buffer. About Quit 
rectangle is copied to the clipboard O. 
and shown in the application’: s cli- 
ent area. 
In order to get the program’s Figure 17-7. SetClipboardData() Example SNAP3. 
window out of the way, SNAP8 mini- 
mizes itself during the capture process. The window is restored when capturing is completed, so 
that the captured image is visible inside of SNAP3’s window. Shenne the “Clear Buffer” menu 
item empties the clipboard. 
- Figure 17-7 shows SNAP3 capturing its own icon's image. This image was created by using 
one instance of SNAP3 to capture a bitmap of a second instance of SNAP3 ee an image of 
the icon of SNAP3!). 


o> Resource Script File 


/* snap3.re */ 
#include “snap3 


eh" 


snap3 ICON snap3.ico 

snap3 MENU - 

BEGIN a oe : : ro se 

; “MENUITEM "&Start Capture” — - _ - IDM_START 
\ ‘MENUITEM “&CLlear Buffer", : = IDM_CLEAR . 


MENUITEM "&About",  . wt IDM_ABOUT. 
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~ 


MENUITEM "@Quit", EDM QUIT 
MENUITEM “\a&Help", -IDM_HELP 
END i. 


& WndProc() and OutlineBlock() Functions 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ coe 


static BOOL bCapturing = FALSE, bBlocking = FALSE ;- 
static POINT om beg, end, oldend; — - 

static short xSize, ySize ; 

static HANDLE hInstance ; 

HDC hDC,. hMemDC ; 

BITMAP bm ; 

HBITMAP hBitmap ; 

PAINTSTRUCT 


a Ps ; 


switch CiMessage) 


{ o : 
case WM_CREATE: ‘/* get program instance */ 
hinstance = GetWindowWord (hWnd, GWW_HINSTANCE) ; 
break ; . 
case WM_COMMAND: /* one of the menu items */ 
switch (wParam) 
a ; { 
a case IDM_START: /* the start capture item */ 
/ bCapturing = TRUE ; 
if bBlocking = FALSE ; 
Hi SetCapture (hWnd) ; /* grab mouse */ 
‘SetCursor (LoadCursor (NULL, IDC_CROSS)) ; 
CloseWindow (hWnd) ; /* minimize window */ 
break ; 
case IDM_CLEAR: /* clears screen and clipboard */ 


OpenClipboard (hWnd) ; 
EmptyClipboard () ; 
CloseClipboard () ; 
InvalidateRect (hWnd, NULL, TRUE) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
case IDM_ABOUT: /* show about box */ 
MessageBox (hWnd, 
“Snap3 - Windows screen capture to clipboard.\nJim Conger 1990.", 
; "Snap3 About", MB_OK) ; 
break ; 
case IDM_HELP: ; ; 
MessageBox (hWnd, “After you click the Start Capture 
menu item, move the mouse to the upper left of 
the area you want to copy to the clipboard. 
Hold down the Left mouse button while you drag the 
mouse to the Lower right of the area. Once you 
release the mouse button, the area is sent to the 
clipboard and shown in Snap3's window.", 
“Snap3 Help", MB_OK) ; 


break ; 
} 
break ; 
case WM_LBUTTONDOWN: /* starting capturing screen */ 
: if (bCapturing) 
{ 
bBlocking = TRUE ; ; 
oldend = beg = MAKEPOINT (lParam) ; 
OutlineBlock (hWnd, beg, oldend) ; 
SetCursor (LoadCursor (NULL, IDC_CROSS)) ; | 
} : i 
break ; 
case WM _MOUSEMOVE: /* show area as rectangle on screen */ 
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if (bBlocking) 


{ “te ~ seeteaede 7 
end = MAKEPOINT (lParam) ; ee aks : : 
OutlineBlock (hWnd, beg, oldend) ; /* erase outline */ 


OutLineBlock (hWnd, beg, end) ; /* draw new one */ 
. oldend = end ; 
} 
break ; ; ; : 
case WM_LBUTTONUP: /* capture and send to clipboard */ z 
if (bBlocking) 
{ 
' bBlocking = bCapturing = FALSE ; 
SetCursor CLoadCursor (NULL, IDC_ARROW)) ; 
ReleaseCapture () ; 3. © /* free mouse */ 
end = MAKEPOINT (lParam) ; 
OutlLineBlock (hWnd, beg, oldend) ; 
xSize = abs (beg.x -— end.x) ; 
ySize = abs (beg.y — end.y) ; 
hDC = GetDC ChWnd) ; 
hMemDC = CreateCompatibleDC ChDC) ; 
hBitmap = CreateCompatibleBitmap 
ChDC, xSize, ySize) ; 
if ChBitmap) 
{ 
SelectObject ChMemDC, hBitmap) ; 
StretchBlt ChMempDC, 0, 0, xSize, ySize, 
hDC, beg.x, beg.y, end.x — beg.x, 
end.y - beg.y, SRCCOPY) ; 
OpenCLlipboard ChWnd) ; 
- EmptyClipboard () ; 
SetClipboardData CCF _BITMAP, hitman) 
CloseClipboard () ; 
InvalidateRect Chuad, NULL, TRUE) ; 
} 
else 
MessageBeep (0) ; 


DeleteDC (hMemDC) ; 
ReleaseDC ChWnd, hOC) ’;' 


} « 
ShowWindow (hWnd, SW_RESTORE) ; /* un-minimize window */ 
break =; | 
case WM_PAINT: /* display contents of clipboard if bitmap */ 
hDC = BeginPaint (hWnd, &ps) ; 
OpenClipboard (hWnd) ; 
if (hBitmap = GetClipboardData (CF_BITMAP)) 


{ ; 
hMemDC = CreateCompatibleDC ChDC) ; 2 
SelectObject (hMemDC, hBitmap) ; 
GetObject (hBitmap, sizeof (BITMAP), ea &bm) ; 
SetStretchBltMode (hDC, COLORONCOLORD ; 
StretchBlt Choc, 0, O, xSize, ySize, hMebc, 0, 0, 

bm. bmWidth, bm.bmHeight, SRCCOPY) ; 

DeleteDC (hMemDC) ; 

} 


CloseClipboard () ; 
EndPaint ChWnd, &ps) ; 
break ; 
case WH_DESTROY: 
PostQuitMessage (0) ; 
break ; 
default: ny 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
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/* OutlineBlock( eieee a rectangle on the screen given the two corner */ 


/* points. 


The R2_NOT style is used, so erawing:! twice on the same location */ 


/* erases the outline. * */ ; ‘ 


“void OutlineBlock CHWND hWnd, POINT beg, POINT end) 
t 


' 


HDC ADC ; 
hDC = CreateDC ("DISPLAY", NULL, NULL, NULL) ; 

' ClientToScreen ChwWnd, &beg) ; /* convert to screen units */ 
ClientToScreen (hWnd, &end) ; 

— SetROP2 ChDC, R2_NOT) ; /* use logical NOT pen */ 


MoveTo ChOC, beg.x, beg.y) 
LineTo (hDC, end.x, beg.y) 


‘LineTo 


LineTo (hDdDC, beg.x, end.y) 


LineTo (hDC, beg.x, beg.y) 
ye : DeleteDdC (hDC) ; 
SerCursoaRpViEWER . ‘gWin 2.0 ‘BWin30 mWin3t 
Purpose Adds a new window to the list of windows in the clipboard viewer chain. iz 
Syntax | HWND SetClipboardViewer(HWND hWnd); | 
Description _ Windows comes with a default clipboard viewing application called Clipboard. It is added to the 
Main program group when Windows is first installed. Other applications can be clipboard view- 
ers, SetClipboardViewer() adds a window to the chain of clipboard viewer windows. Windows in 
the clipboard viewer chain receive WM_DRAWCLIPBOARD messages any time the clipboard data ~ 
is changed. This is the signal to display the clipboard data, if the data format is known to the’ ; 
viewer program. Viewers must pass WM_CHANGECBCHAIN messages to the next window in the’ 
chain. Viewers mist also remove themselves from the chain when they are about to terminate, 
(WM_DESTROY message processed). ChangeClipboardChain() does this function: 
Uses Adding a window to the clipboard viewer chain. 
Returns HWND, the handle of the next window in the clipboard viewer chain. This value should be saved 
; as a static variable, as it will be needed to process WM_DRAWCLIPBOARD, WM_CHANGE- 
CBCHAIN, and WM_DESTROY messages. 
See Also ChangeClipboardChain() 
Parameters 
hWnd HWND: The window handle for the window to be added to the clipboard viewer chain. 
Related Messages WM_DRAWCLIPBOARD, WM_CHANGECBCHAIN 
Example 


/* draw rectangle */ 


ChOC, end.x, end.y) 


we Wa No Be Ve 


See the example under ChangeClipboardChain() for aclipboard viewer listing that handles both 
text and nee clipboard data. 
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Windows provides 17 functions for sound support. Considering the limited hardware support for sound production on 
the IBM PC family of computers, 17 is a commendable number. Unfortunately, many of these functions require addi- 
tional hardware to produce reasonable sounding musical notes and sound effects. Sound hardware varies from simple 
tone generators to compact disk quality external sound devices. Windows provides only basic functionality for produc- 
ing sequences of sounds, and a limited amount of control over the sound types. For more complete control, specialized 
sound drivers and programs are required. 


Sound Sources 


The speaker attached to the IBM PC family of computers is a i ciple device. Sound paiten are generated by the 
computer 'atiming chip. The timer sends a series of pulses to the speaker. The faster the pulses, the higher the pitch. 
Clever pr rammers have found ways to‘get more than a beep out of this speaker. For Windows’ purposes, we can 
! | speaker to be little more than a beeper. You can generate monophonic (one note at a time) music by 
controllin he speaker under Windows, but it is dreadful to listen to. 

_ The next level up from the PC speaker is to install an internal sound card in the PC. The most popular boards are 
the Adlib Baard, the Sound Blaster Card, and the IBM Music Feature Card. All of these include a sound synthesis chip. 
The chip can be programmed to provide a wide range of sounds, roughly simulating both musical sounds and sound 
effects. In addition, the Sound Blaster Card provides input and output of sampled sounds (for example, recording and 
playing back voices recorded to disk from a microphone). These internal cards use 8-bit sound resolution, which 
. means that the sound waves are recorded and generated by measuring the wave amplitude with 8-bit numbers. The 
result is acceptable sound for game applications and limited room-size presentations. Eight-bit sound is net accept- 
able for amplification for use in larger rooms, or in serious musical applications. 

Obtaining high quality sound requires 16-bit sound resolution. (The resolution that compact disk (CD) players 
use to store and replay music). Sixteen-bit resolution sound provides professional quality sound for studio use, and it 
is completely| cceptable for amplification for presentations in large rooms and auditoriums. Roland Corporation 
markets several internal PC boards that have 16-bit resolution. Most 16-bit sound sources are complete synthesizers 


that are much {oo large to fit inside of a PC. These external sound “boxes” ate controlled by connecting them to the 
computer with\tables. A standard communication protocol called “MIDI” (Musical Instrument Digital Interface) 
allows the computer to control the, sound sources, and also to record Keybaary playing if the ue source has a 


keyboard. |" \ 

Microsoft dffers MIDI support as part of a Windows Multimedia Developer’ S Kit. Hopefully, Microsoft will add 
MIDI support olatr releases of Windows. MIDI drivers for Windows can also be purchased from Playroom Software, 
although their cutrent release only supports Windows’ real and standard mode operations (not enhanced mode). For - 
the purposes of this book, we will assume that the reader i is either limited to the PC speaker or has an inexpensive 
internal sound board attached. References for other sound sources are included in the bibliography. 


Sound Drivers , 
The SYSTEM.INI file that Windows uses to initialize devices on startup includes a line specifying the sound driver: 
sound. drv= sound. drv 
’ SOUND.DR is the default Windows sound driver. This file is loaded into the SYSTEM subdirectory when Windows 
is installed. The oo nape the patel as functions for controlling the PC speaker. | ' 


‘ 
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If another sound device is installed in the PC, Windows.will not immediately know how to access it. The sound 
- card manufacturer will (or at least should) supply a specialized driver file for the board. To use the new sound source, _ 
edit SYSTEM.INI to include the name cf the new driver. For Sane the driver FM. DRV use , 


sound.drv= fn. drv 


“Installing the Windows driver does not immediately provide support for all of the Windows sound functions. Three 
of the functions are so specialized that many sound boards will not be able to use them. This limitation is because the 
internal architecture of the sound board’s hardware may not match the assumptions that Windows’ developers made 
when they created these three functions. The functions are SetSoundNoise(), SetVoiceEnvelope(), and Set- 
VoiceSound(). The remaining 14 functions should work regardless of the sound hardware, assuming that the sound 
driver has been written correctly. (The sound functions were originally developed for the IBM PC Junior, which had a 
simple sound chip.) ; 


Voices and Voice Queues. 


~ The lowly PC speaker can play only one note at a time. Internal sound boards typically allow iiuen eight and 16 

sounds to be output at once. Windows refers to each separate sound type as a “voice.” To keep track of when to play 
. each note, Windows uses the concept of a note queue. A queue is just a list of notes stored in memory. All of the notes 
_ ’» that are to be played for each voice are loaded into a queue in the order that they are to be played. When the play 
process is started, the notes are read from each queue and played. The queues shrink as the notes are played. The 
queues are empty (occupy no memory) when all notes 
have been played. Figure 18-1 illustrates a voice queue. Voice Queues 

A minimum program fragment that will load and 

play a series of notes is shown in Listing 18-1. The . : 
OpenSound() function takes control of the system’s VOice2 }F* Aaa ieee 
sound device. Only one device has control of the sound Voice 3 ee es 
source at a time. The application calling OpenSound() aimee ema 
retains control of the sound device until it calls Close- 
Sound(). 


© Listing 18-1. Playing C One Voice The First Notes Individual 


Figure 18-1. Voice Queues. : 
if (OpenSound() > 0) ee “ 
{ 


Voice 1 


SetVoiceaueucsize (1, 30) ; ; / 
SetVoiceAccent (1, 120, 128, Ss NORMAL, 0) ; 
for (i =O; i1<5 3 i++) : ; 
peuvorcenere (1, i + 20, 8, 0); p 
StartSound() ; a 
} 
_ The size of the memory buffer for the note data is set with SetVoiceQueueSize(). In this case, 30 bytes are re- 
served. This is enough room for six notes. The tempo and volume are set with a call to SetVoiceAccent(). Five notes are 
added to the voice queue by repeatedly calling SetVoiceNote(). Finally, StartSound() is called to start playing the 
notes. Windows will play the notes in the background, while continuing to process messages and run other applica- 
tions. This is convenient for the programmer, as you can “set and forget” the sound functions in most cases. 
Elsewhere in the program, the program will need to be able to shut down the sounds, if they are still playing, and 
release the sound device to Windows for use by other applications. StopSound() stops playback of any voice a 
that have been playing. CloseSound() returns control to Windows. (See Listing 18- 2. De 


© Listing 18-2. Stopping Sound Playback ee 


StopSound () ; 
; CloseSound (). ; 7 
~ These examples have used only one voice and are compatible with programming the PC’s speaker usirig the 
‘default SOUND.DRV driver. For more advanced sound sources, you will need to know the number of voices available. 


r 


18. SOUND FUNCTIONS ¥V 


OpenSound() returns this value. OpenSound() will return a negative integer if the sound source is not available, 
meaning that another application has control of the sound source. If you program more than one voice, be sure to call 
. SyncAllVoices() to keep the playback of each voice synchronized with the others. 

When the voices have been played, the memory buffers that held the voice data are emptied. This means that the 
voice data has to be reloaded each time that the data is to be played. Voice queues occupy locked global memory. 
These locked blocks of memory will clog up the global heap from the time the voices have been allocated with 
SetVoiceQueueSize() until the time the play process is over. 

You may notice the system performance being degraded by these locked blocks. To minimize the impact of the 
locked voice queue data, do not load the voice queues until right before the sounds are to be played. 


Voice Thresholds 


You may want to keep track of when avoice goes beyond a certain note. For example, you might want a graphics image 
to appear in sync with music in a presentation. Windows allows for this by allowing each voice to have a “threshold” 
value. This value is the number of notes remaining when an action should occur. For example, if a program needs to 
display a graphics object when 100 notes remain in voice queue 2, then the threshold for queue 2 would be set to 100. 

Threshold values are set for each voice that requires one with the SetVoiceThreshold() function. The status of up 
to 16 voices can be checked with a call to GetThresholdStatus(). Typically, a Windows program will start the play 
process, and then check the threshold status for a track at intervals. The system clock can be used to trigger a periodic 
check of the track threshold status. 


Sound Function Error Codes 


All of the sound functions that return integer status values use the convention that errors are returned as negative 
numbers. In most cases, it is not important which error occurred. If you need this information, the error codes are 
defined in WINDOWS.H as follows: 


#define S_SERDVNA (-1) /* Device not available */ 


. #Hdefine S_SEROFM (-2) /* Out of memory */ 

Hdefine S_SERMACT (-3) /* Music active */ 

#define S_SERQFUL (-4) /* Queue full */ 

#define S_SERBDNT “(-5) /* Invalid note */ 

H#define S_SERDLN . (-6) /* Invalid note length */ -_ 
’ Hdefine S_SERDCC (-7) /* Invalid note count */ ; , 

#define S_SERDTP (-8) /* Invalid tempo al ka 

H#define S_SERDVL (-9) /* Invalid volume */ 

H#define S_SERDMD (-10) /* Invalid mode */ 

#define S_SERDSH (-11) /* Invalid shape . */ 

H#define S_SERDPT (~12) /* Invalid pitch */ 

Hdefine S_SERDFQ (-13) /* Invalid frequency */ 

define S_SERDDR (-14) /* Invalid duration */ 

#define S_SERDSR (-15) /* Invalid source */ 

adefine S_SERDST (-16) /* Invalid state x] 


Sound Function Summary | 
Table vi 1 summarizes the Windows sound functions. The detailed function dicseviplions are in en next section. 


. CloseSound Shuts down the play process. 
CountVoiceNotes ~ Determines the number of notes in a note queue. 
GetThresholdEvent Checks all voice queues to see if the threshold value has been surpassed. 
GetThresholdStatus Checks all voice queues:to see if the threshold value has been passed. 
MessageBeep Beeps the sound device. 
OpenSound Provides the application with access to the sound device. 
SetSoundNoise Sets the noise waveform table for a sound device. 


SetVoiceAccent ‘Sets the tempo, volume, mode, and pitch offset for a voice. 


a 
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Table 18-1. continued 


SetVoiceEnvelope 


SetVoiceNote 
SetVoiceQueueSize 
SetVoiceSound 
SetVoiceThreshold 
StartSound 
StopSound 
SyncAllVoices 
WaitSoundState — 


Speci ies the sound waveiom to use fe a voice. 

Adds a note to a voice queue. 

Sets the size of the memory buffer to hold the note values for a voice. 
Sets the sound frequency of a voice in a voice queue. 

“Sets a number of notes in the voice queue that will trip the threshold status. 
Starts all voice queues playing. 
Stops the play process. 

Synchronizes the timing of playback of notes from several voice queues. 


Stops Windows from regaining contro! until one or more voice queues surpasses a threshold 
’ state or is empty. 


Table 18-1. Sound Function Summary. 


Sound Function Descriptions 
_ This section contains the detailed description of the Windows sound functions. 


C1LosESouUND 
Purpose 

Syntax 
Description 


Uses 
‘Returns 
See Also 
Parameters 


- Example 


aWin2.0 eWin30 g&Windl-- 
Shuts down the play process. . 
void CloseSound(void); — 
This function stops all voice queues currently playing, frees memory associated with the voice 


_ data, and releases the sound device for use by other applications. 


Every call to OpenSound() should have a matching call to CloseSound(). 

No returned value (void). 

OpenSoundQ) 

None (void). 

This example will play five notes on nite PC speaker when the user clicks the “Do It!” menu item. 
The program displays the number of voices available each time the menu item is clicked. (This 
number will be 1 for a standard PC without a sound card installed.) If “Do It!” is clicked more 
than once, a free voices value of —1 will be displayed because the sound source has already been 


opened. The sound source is not freed until the user clicks the “Quit” menu item. If another 
Sound device and driver have been installed, the notes will be played on that device. 


Long Far PASCAL WndProc CHWND hWnd, nesne) it daca WORD wParam, LONG LParam) . 
€ 


* HDC hdc ; 
“dat i> nvotce 4 
char cBuf C128] 7 
switch CiMessage). , , /* process windows messages */ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) = 
{ 


case IDM_DOIT: /* User hit the “Do it" menu item */ .. 
; hoe = GetDC ChWnd) >; . ; 
if (CnVoice = dpensoundt)? > 0) . 
{ es : 
TextOut choc, 10, 10, cBuf, wsprintf (cBuf,. 
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"4d voices free.", cnvotce)) 3 
SetVoiceQueueSize (1, 30) ; 
SetVoiceAccent (1, 120, 128, S_NORMAL, 0) ; 
for CG =Q; 1<5; itt) 

SetVolcenore C1, i+ 20, 8, 0) ; 


: _StartSound() ; 
} 
ReleaseDC (hWnd, hDC) ; 
break ; 


case IDM_QUIT: : 
DestroyWindow ChWnd) ; 
break ; 
} . 
break ; 
case WM_DESTROY: /* stop application */ 
StopSound () ; 
CloseSound ()'; 
PostQuitHessage (0) ; 
break ; 
default: /* default windows message processing */ 
- return DcfWindowProc (hWnd, iMessage, wParam, (Param) ; 


} 
return (OL) ; 


} 

CountVoIcENOoTEs | aWin20 @Win3.0 wWin3.1 
; Purpose Determines the number of notes in a note queue. 

Syntax int CountVoiceNotes(int nVoice); 


Description - The SetVoiceNote() function is used to add notes to a voice MN ae ict. [= 
: queue. When the StartSound() function has been called, Fae UDI ME AA Gees 


CountVoiceNotes() will return the number of notes leftinthe  § Do rm ; Quit | 
queue. The function will return zero if StartSound() has not {-—— — i 


been called, or if all of the notes have been played. 


Uses 7 Determining the position in a song. eee A 

Returns int, the number of notes remaining in the note queue. Figure 18-2. CountVoice- 

See Also SetVoiceNote() Notes() Example. 

Parameters 

nVoice . int: The voice number. The first voice is numbered 1. OpenSound() returns the number of voices 
, that are available on the sound device. 

Example This example plays five notes when the “Do It!” menu itemi is 3 clicked, as shown in Figure 18-2. ‘The 


note count is checked right after StartSound() is called, so all of the notes are in the queue. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
¢ 


HDC hDC ; 
int i, nNotes ; f 
char cBuf C128) ; 
switch (iMessage) /* process windows messages */ 
case WH_COMMAND: : /* process menu items */ © 
switch (wParam) . 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
¥ hOC = GetDC ChWnd) ; 
ne if COpenSound() > 0) 
{ 


SetVoiceQueueSize (1, 30) ; 
SetVoiceAccent (1, 120, 128, S NORMAL, 0) ; 
HOES nd Ss i++) 


745. - a ; 


T-?!; 


wowwuywwo Ar! DIGLE . 


SetVoiceNote (1, 1+ 20, 8, 0) ; 


- StartSound() ; 


nNotes = CountVoiceNotes (1); 
TextOut (hDC, 10, 10, cBuf, wsprintf (cBuf, 


"Zd notes." 


} 


ReleaseDC (hWnd, hDC) ; 


break ; 

case IDM_QUIT: 
StopSound () ; 
CloseSound () ; 


DestroyWindow ChWnd) -; 


ee, break ; 
[Other program lines] 


GETTHRESHOLDEVENT (Requires sound device and sound driver) 


, NNotes)) ; 


/* send end of application message */ 


Win2.0 wWin3.0 em Win3l 


Purpose Checks all voice queues to see if the threshold value has been passed. 
Syntax _ LPINT GetThresholdEvent(void); 
Description The SetVoiceThreshold() function is used to set a note count called the “threshold” value. As the 


play process continues, the number of notes in each note queue decreases. When the number of 
notes remaining is less than the threshold value, the threshold status is true. The returned value 
from GetThresholdEvent() is a pointer to an integer that encodes the threshold status of every: 
note queue as a binary number. The bit is set to 1 if the threshold value for the queue has been 
passed, or to 0 if not. The least significant bit is for track 1. 


Uses This function can be used to synchronize other activities to the sound/music playing. The thresh-- 
old status can be checked periodically to determine if a threshold value has been passed. If so, 


some action, such as displaying a graphics image, can 


be taken. 
Returns LPINT, a far pointer to a memory buffer that contains 
the 16-bit value, encoding the threshold status of each 
track. 
See Also SetVoiceThreshold(), GetThresholdStatus() 
Parameters None (void). 
. Example 


generic [> 
ithe Threshold Flag = Ox1ff 


Figure 18. 2 GetThresholdEvent( ¥ 
Example. 


This example, which is illustrated in Figure 18-3, is designed for a sound device with nine or more 


voices. The program sets nine voice queues with five notes each, and sets 4 threshold value of 
three notes in each queue. GetThresholdEvent() is used to obtain a pointer to the memory area. 
where Windows stores the threshold flag value. The threshold value is determined to be Ox ff, - 
showing that all nine queues have tripped their threshold values (Ox1ff = 111111111 binary). 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ; 


HDC hdc ; 

static int nVoices ; 

‘int i, nActiveVoice ; 
LPINT ; lpEvent ; 

char cBuf [128] ; 


switch (iMessage) 


case WM_CREATE: 
nVoices = OpenSound() ; 
hi (nVoices < 0) 


/* process windows messages */ 


/ MessageBox. (hWnd, “Could not open sound device.", 
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“Error'", MB_ICONHAND |-MB_OK) ; 
-DestroyWindow ChWnd) ; 
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break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ ; 
case IDM_DOIT: /* ‘User hit the “Do it" menu item */ 
hDC = GetDC ChWnd) ; 
a: for (nActiveVoice ="1 ; nActiveVoice <= nVoices ; 
nActiveVoicet+) 
{ 
SetVoiceAccent (nActiveVoice, 120, 128, 
S_NORMAL, 0) ; 
SetVoiceEnvelope (nActiveVoice, nActiveVoice, 
; 100) ; 
SetVoiceQueueSize (nActiveVoice, 256) ; 
for (i =0; 1<5 3; itt) 
SetVoiceNote (nActiveVoice, i + 20, 
8, 0); 
‘ SetVoiceThreshold (nActiveVoice, 3) ; 
} i 
SyncALlVoices () ; 
StartSound() ; 
lpEvent = GetThresholdEvent () ; 
TextOut (hDC, 0, 0, cBuf, wsprintf (cBuf, 
"The Threshold Flag = Ox%x", *lpEvent)) ; 
ReleaseDC (hWnd, hDC) ; 
break ; . 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; : 
break ; . : 
} 
break ; 
case WM_DESTROY: /* stop application */ 


StopSound () ; 
CloseSound () ; 
PostQuitMessage (0) ; 
; break ; ad 
default: /* default windows message Processing x] 
return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 


return (OL) ; 


GETTHRESHOLDSTATUS (Requires sound device and sound driver) Win2.0 ef Win 3.0 Win 3.1 


Purpose 
Syntax 
Description 


Uses 
Returns 


‘See Also 


Checks the threshold status of all voice queues. 
int GetThresholdStatus(void); 


The SetVoiceThreshold() function is used to set a note count called the “threshold” value. As the 
play process continues, the number of notes in each note queue decreases, When the number of 
notes remaining is less than the threshold value, the threshold status is true. The returned value 
encodes the threshold status of every note queue as a binary number. The bit is set to 1 if the 
threshold value for the queue has been passed, or to 0 if not. The least significant bit is for track 
1. This function is similar to GetThresholdEvent(), except that GetThresholdStatus() also clears 
the event flags. 


‘This function can be used to serehconia other activities to the sound/music playing. The thresh- 
old status can be checked periodically to determine if a threshold value has been passed. If so, 


some action, such as displaying a graphics image, can be taken. 


int, the bit-coded threshold status for each track. The bits will be one for the tracks which are 
currently below the threshold value. For example: 101 binary (5 decimal) codes as one and 
three as being below the threshold value. 


SetVoiceThreshold() 
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Parameters "None. (void). 


Example — See the example under the SetVoiceThreshold() funetion description. 

MEssAGEBEEP ep |  gWin2.0 «m@Win3.0 Wind. 
Purpose ‘Beeps the oe device. 

Syntax void MessageBeep(WORD w7ype); 

Description _ This is the easy way to have the PC speaker or installed sound board beep. 

Uses Use to alert the user. Commonly associated with error and warning messages. A good use is to 


‘summon the user after a background task, such as a long file transfer, | is complete. 
Returns ~~ , No returned value (void). 


See Also _ MessageBox() 

Parameters oo 
wType WORD: This value is not used. Set equal to zero. . 
Example ' This example shows a typical use of MessageBeep(), immediately before MessageBox(). 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG (Param) 
{ 
switch (iMessage) /* process windows messages sf A 


case WH_COMMAND: . /* process menu items */ 
switch (wParam) | : 
{ 


case IDM_DOIT: a User hit the "Do it" menu item */ 
a: MessageBeep (0) ; 

. MessageBox cavnds "This is a warning message", 
“Warning", MB_ICONASTERISK | MB_OK) ; 


f break ; 
[Other program lines] 
OreNSounD. a mWin2.0 .@Wind.0. a Wind! 
Purpose Provides the application with access to the sound device. 
Syntax int OpenSound (void); 
Description Only one application can have access to the sound device at one time. The sound device is con- 


trolled via a driver file that is specified in the Windows SYSTEM.INI file with a line like 
sound. drv=fm. drv. 


OpenSound() returns the number of voices available on the sound device. This is the number 

7 of independent sound waveforms that can be played at once. As soon as one application has 
a ” called OpenSound(), all other applications will receive a negative value from OpenSound() if 
-. they attempt to use OpenSound() to access the sound device. The sound device i is returned to the 


Gap tite _ system with CloseSound(). _ 
Uses ~~ This is the first step in starting the play process. ; 
Returns ‘ “int, the number of voices available. For the default SOUND.DRV driver that runs the PC’s speaker, 


this will be 1. Returns a negative value if the sound driver has been opened by another applica- 
tion, or has been opened earlier in the same program without a call to CloseSound(). 


See Also CloseSound() . 
Parameters None (void). , 
Example See the example under the'CloseSound() function description. 
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SETSOUNDNOISE (Requires sound device and sound driver) eWin2.0 oWin3.0 Win 3.1 

Purpose Sets the noise waveform table for a sound device. . 
Syntax : int SetSoundNoise(int nSource, int nDuration); 

Description Some sound drivers allow the sound wave table to be programmed. This function allows one of a 


number of “noise” wave tables to be specified. Noise waveforms find wide application in sound 
effects for explosions, engines, etc. 


Uses Used with specialized sound devices. This function will have no effect if the default SOUND. DRV 
driver is being used to drive the PC speaker. 

Returns int, zero if successful. Returns S_SERDSR if the xSource value is not valid. 

See Also SetVoiceEnvelope(), SetVoiceSound() 

Parameters | a 

nSource int: One of the values in Table 18-2. 


S. PERIODS12 High-pitch hiss. 


S_PERIOD1024 Hiss. *. 
S_PERIOD2048 . Low-pitch hiss. 
S_PERIODVOICE Source frequency from voice channel 3 (device dependent). - 
S.WHITES12—~ * High-pitch noise. 
S.WHITE1024. Noise. 
S_WHITE2048 ’ Low-pitch noise. . 
S_WHITEVOICE _ Source frequency from voice channel 3 (device deperident). 
Table 18-2. SetSoundNoise{ ) Values. 
Example In this example, SetSoundNoise() is used as part of a play function. The author does not have a 


sound device that responds to this command. This is only a demonstration. 
long FAR PASCAL WndProc CHWND hWnd, wneianed iMessage, WORD wParam, LONG lParam) 
€ : . : 


‘static int . nVoices ; 

int i, nActiveVoice ; 

switch (iMessage) /* process windows messages */ 
{ F 


case WM_CREATE: 
; nVoices = OpenSound() ; 
if (nVoices <= 0) 


{ 

MessageBox (hWnd, “Could not open sound device.", 
“Error", MB_ICONHAND | MB_OK) ; 

DestroyWindow (hWnd) ; 

} 

break ; 

case WH_COMMAND: /* process menu items */ 

switch (wParam) 

{ ; 

case “IDM_DOIT: /* User hit the Po it’ menu item */— 


SetSoundNoise (S PERIOD1024, 100) ; 
for (nActiveVoice = 1 ; nactivevatce <= DYOTEES ; 
" nActiveVoicet+) ‘ 8 
{ 
SetVoiceAccent (nActiveVoice, 120, 128, 
S_NORMAL, 0) ;¢ 


749 


WINDOWS API BIBLE 


SetVoiceQueueSize Enkeriveveice: 256) ; 
for (i=0; 1<5 3 it+) 
SetVoiceNote (nActiveVoice, i + 20, 8, 0); 
} 
_ SyncAllVoices () ; 
. StartSound() ; j 


break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow ChWnd) ; 
break ; 
} i 
break ; 
case WM_DESTROY: /* stop application */ 


StopSound () i 
CloseSound () ; 
Postaui tMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; 


} 

SeETVOICEACCENT eWin2.0 @Win3.0 wm Win31 

Purpose Sets the tempo, volume, mode, and pitch offset for a voice. 

Syntax int SetVoiceAccent(int nVoice, int nTempo, int nVolume, int nMode, int nPitch); 

Description Accents can be placed, at any point in a voice’s play pattern. The number of parameters that 
SetVoiceAccent() will affect depends on the sound driver in use. 

Uses Used to change the volume and tempo of a song, Can also be used to transpose a portion of the 

song by setting nPitch to a nonzero value. : 

Returns int, zero if the function was successful. If an error occurs, one of the values in Table 18-3 will be 

returned. 


So SERDMD i Invalid mode. 


‘S SERDTP \, (| Invalid tempo. 
S_SERDVL | | Invalid volume. 
S_SERQFUL Queue full. 


Table 18-8. SetVoiceAccent() Error Codes. | o ! 


See Also SetVoiceQueueSize() 


Parameters : 

nVoice int: The number of the voice that will receive the added note. The first voice is. number 1. 

nTempo int: The tempo in beats (quarter notes) per minute. The valid aan is from 32 to 255. The default 

value is 120. ° 

nVolume int: The voice volume level, 0 to 255. This parameter will not affect the default SOUND.DRV driver 
for the PC speaker. 

nMode int: Specities how the notes are to be played. This parameter will not affect the default 


SOUND.DRV driver for the PC speaker. For other drivers and devices, the value may change the 
duration of the notes. nMode can be set to any of the values in Table 18-4. 


750 


18. SOUND FUNCTIONS V 


S_LEGATO Note divalion will continue into the next beet overlapping the next note, in order to prcvide a 


“smooth” musical style. 
S_NORMAL . Note durations will stop at the end of the beat. 
S_STACCATO - Note duration will stop before the end of the beat, leaving an open period between notes, in 


order to provide a “choppy” musical style. 
Table 18-4. SetVoiceAccent() Mode Values. 


nPitch int: The pitch offset to add to the notes. This offset is used to transpose note values. Possible 
range is 0 to 83. 

Example See the example under the CloseSound() function description. 

SETVOICEENVELOPE (Requires sound device and sound driver) Win 2.0 Win3.0 Win3.1 

Purpose Specifies the sound waveform to use for a voice. 

Syntax int SetVoiceEnvelope(int nVoice, int Shape, int nRepeat); 

Description This function changes the wave shape used by a sound device to produce a sound. The wave shape 
change is set to occur at the current location in the note queue. This allows voices to be altered in 
the course of playback. 

Uses Used with sound devices that have tables of wave shapes. This function will have no effect if the 
default SOUND.DRV driver is being used to control the PC speaker. ; 

Returns int, zero if the function was successful. If an error occurs, one of the values in Table 18-5 is 
returned. 


S_SERDRC Invalid repeat count. 
S_SERDSH Invalid shape. 
S_SERQFUL Queue full 2 
Table 18-5. SetVoiceEnvelope() Error Codes. 
See Also — ~ SetVoiceSound(), SetSoundNoise() 
Parameters : 
nVoice int: The number of the voice that will receive the added note. seep errr 
The first voice is number 1. = generics oe [EF 
nShape int: The index number of a sound device wave shape. This num- 
~ - ber will depend on the hardware sound device in use. eync valbe™ DP iyoleer = 2 
nRepeat int: The number of times the wave shape should be repeated — Figure 18-4. SetVoice- 
_ during the duration of one note. This number is hardware de- Envelope() Example. 
pendent. . 
Example This example plays the same five notes simultaneously on every available voice of the sound 


device when the user clicks the “Do It!” menu item. As shown in Figure 18-4, the used device has - 
nine voices. The frequency of the waveform used for each voice is set to 440 Hz with. 
SetVoiceSound(). SetVoiceEnvelope() is used to specify the first nine preset sound patterns. 
SyncAllVoices() is used to make sure the notes are played at the same time on each voice. 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{. 


HDC hOC ; 

static int nVoices ; 

int ; i, nActiveVoice, nSync ; 

char cBuf [128] ; 

switch (iMessage) | /* process windows messages */ 
Ct. : , 


case WM_CREATE: 
a nVoices = OpenSound() ; 
if (nVoices <= 0) 
{ 
MessageBox (hWnd, "Could not open sound device."”, 
“Error", MB_ICONHAND | MB_OK) ; 
DestroyWindow (hWnd) ; 
} 
break ; . 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC (hWnd) ; ; 
for (nActiveVoice = 1 ; nActiveVoice <= nVoices ; 
nActiveVoicet+) 
{ 
SetVoiceSound (nActiveVoice, 
(LONG) (440 << 16), 100) ; 
SetVoiceEnvelope (nActiveVoice, 
nActiveVoice, 100) ; 
SetVoiceAccent (nActiveVoice, 120,:128, 
S_NORMAL, 0); -:. : 
SetVoiceQueueSize (nActiveVoice, 256) ; 
for (i =0;.i1<5 ; itt) 
‘ SetVoiceNote (nActiveVoice, i + 20, 8, 0) ; 
nSync = SyncALllVoices () ; 
TextOut ChDC, 0, 0, cBuf, wsprintf (cBuf,: 
“Sync value = 4d, Voices = %d", nSync, nVoices)) ; 
StartSound() ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} 
, break ; S5 
case WM_DESTROY: /* stop application */ 
StopSound () ; : 
CloseSound () ; 
PostQuitMessage (0) ; 
break ; . i 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; 


} . hast 
SeTVoIcENoTE. | | mWin20 @Win30 . Wind... 
Purpose fs, ‘Adds a note to a voice queue. © . 
Syntax : ve int'SetVoiceNote (int nVotce, int nValue, int nLength, int nCDots); 
Description | i : nn a voice queue's memory buffer has been allocated with SetVoiceQueueSize(), notes can be _ 
7.7... . '” added to the queue with this function. Each note is added to the end of the queue. If the number 
. ' of notes add d exceeds the queue size allocated, additional calls to SetVoiceNote() are ignored. 

| The notes will not be played until StartSound() is called. 

Uses Putting a musical pattern into the voice queue, prior to playing the pattern. 
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Returns . int, zero if the function added the note to the queue. If a an error occurs, one of the values i in Table 
18-6 will be returned. . 


S SERDCC Invalid dot count. 


S_SERDLN Invalid note length. 
S_SERDNT  ” Invalid note number 
S_SERQFUL The note queue is full. 
Table 18-6. pelloweNotn ) Error Values. 
See Also. Be WoleeQueneslze 0; StartSound() 
‘Parameters 
nVoice - int: The number of the voice that will receive the added note. The first voice is number 1. 
nValue int: The number of the note. Note numbers range from 1| to 84. Zero is used for a rest (time period 
with no note sounding). The pArequency of the note auecified will depend on the sound device in - 
use, . 
nLength ‘int: The duration of thie note. 1 for a. whole n note Xo beats), 2 for a half note e beats), 4 fora. 
. quarter note (1 beat), etc. . 
nCDots int: The number of half-duration: increments to add to the note eal This is not the same as 


adding musical dots. For example, ifnLength is 2, the basic note value will be two beats. IfnCDots 
is then set to 1, the duration will be three beats. IfnCDois is set to 2, the duration is four beats. 


Example See the example under the CloseSound() and SetVoiceEnvelope() function descriptions. 
SETVOICEQUEVESIZE 7 mWin2.0 i Win38.0 mm Win3.1 
Purpose Sets the size of the memory buffer to hold the note values for a voice. . 

. Syntax | int SetVoiceQueueSize(int nVoice, int nBytes); . 

. Description Windows stores each voice’s note data ina separate memory buffer. The SetVoiceNots() function 


adds notes to the buffer. Each note occupies six bytes of memory. To make room for the note data, 
SetVoiceQueueSize() should be called before SetVoiceNote() is used to put notes into the buffer. 


Uses Used to allocate memory for a voice’s note data. The memory block is freed when CloseSound() i is 
called. -_ 
Returns int, returns zero if the function was uceecsful Returns ¢ one of the values in Table 18- 7 if an error 
; was detected. 


‘Ss " SERMACT The device is currently playing. 
S_SEROFM 7 Out of memory. , 


Table 18-7. SetVoiceQueueSize() Error Codes. 


See Also SetVoiceNote() 


Parameters . . . 

nVotce int: The number of the voice. The first voice isnumber1. 

nBytes ._ int: The number of bytes to allocate. Each note requires six bytes. The default buffer size is 192 
_ bytes (82 notes), 

Example See the example under the CloseSound() and SetVoiceEnvelope() tinction descriptioiis 
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SETVOICESOUND (Requires sound device and sound driver) @ Win 2.0 Win3.0 wmwWin31 - 

Purpose Sets the sound frequency of a voice in a voice queue. 

Syntax _ int SetVoiceSound(int nVoice, LONG lFrequency, int nDuration), . 

Description _—* This function changes the frequency used by a sound device to produce a sound. The wave shape 
1s change is set to occur at the current location in the note queue, which allows voices to be altered 
in the course of playback. : 

Uses : Used with sound devices that have variable frequency sound generators. This function will lave 

8 oy ee no effect if the default SOUND.DRV driver is being used to control the PC speaker. 
Returns _ int, zero if the function was successful. If an error occurs, one of the values in Table one is 
returned: 


S_SERDDR Invalid duration, 


S SERDFQ Invalid frequency. | 
S_SERDVL Invalid volume. . pt 
S_SERQFUL Queue full . — : | 
Table 18-8. SetVoiceSound() Error Codes. f 
See Also SetVoiceEnvelope(), Snes: : . 
Parameters "y . 
nVoice int: The number of the voice that will receive the added note. ‘The va voice is number 1. . 
lFrequency LONG: The frequency to set. The high-order word contains the frequency in cycles per second 
(Hz). The low- order word contains the fractional frequency (usually zero). . 
nDuration int: Sets the duration of the sound in system clock ticks. (This may not impact the sound, depend- 
ing on the sound hardware i in use.) 
Example See the example under the SetVoiceEnvelope() function description. 


SetTVoICETHRESHOLD (Requires sound device and sound driver)  @Win2.0 @Win3.0 mWin3.1 


Purpose Ss Sets the number of notes in the voice queue that will trip the threshold status. 
Syntax “a int SetVoiceThreshold(int nVoice, int nNotes); 
Description The “threshold” i is a number of notes in a voice queue. As the voice queue is played, the number of 


remaining notes declines. When the number of remaining notes falls below the threshold value, 
_ the threshold is said to have been passed. The current threshold status on all voices can be 
checked at-any time with GetThresholdStatus(). The WaitSoundState() function will suspend © 
Windows message PreceSinG until the threshold number is surpassed on one or more voice 
queues. 
Uses Normally used in conjunction with GetThresholdStatus(). The application can start music play- 
ing, and then periodically check the threshold status (perhaps with a timer, or when any Win ~ 
dows message is received). When the threshold is surpassed, the application’ can take some 
action, which will then be synchronized with the music. ; 


Returns int, zero if the function is successful, 1 if nNotes is out of range. 


See Also GetThresholdStatus(), WaitSoundStateQ) - 
Parameters : 7 
nVoice int: The number of the volce queue to set the threshold value. The first voice queue is number 1. 
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int: The threshold number of noteS xyes ra arene recrme = 
_ for the voice queue. This value must oe eS ogenericn ey fe Ae 

be less than the number of notes in Do lt! Quit 

the queue. CountVoiceNotes() can =~ — ; 

be used to determine the numberof ¥oices = 9, Threshold Status = Oxt1ff § 


notes in a queue. All 9 voices done. 


This example, which is illustrated in oan SS PT 

Figure 18-5, was run with a device Figure 18-5. SetVoiceThreshold() Example. 

with nine voices. The program loads 

all nine voices with a five note song, and sets a threshold value of three notes in each voice queue. 

The Threshold status value is displayed on the top line. The value of Oxiff shows that all nine 
~ voices have a threshold value set (111111111 binary = Oxlff). Unlike the normal case of letting 

the music play while Windows continues to process other messages, this example calls 
_ WaitSoundState() to wait until all nine voice queues are empty before returning contro] to Win- 

dows. When the WaitSoundState() returns (voice queues empty), a message is shown on the 
"second line. 


paEAR PASCAL lindProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


HOC 
sta 
int 
cha 


swi 
{ 


hDC ; 
tic int nVoices ; 
i, nActiveVoice, nTStatus ; 
Ly cBuf £1281 ; 
tch (iMessage) /* process windows messages */ 


case WM_CREATE: 
nVoices = OpenSound() ; 
if (nVoices <= 0) 
{ 


MessageBox (hWnd, “Could not open sound device.", 
“Error"™, MB_ICONHAND | MB_OK) ; 
DestroyWindow (hWnd) ; 
} 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 


case IOM_DOIT:  J* User hit the "Do it’ menu item. */ 
hOC = GetDC ChWnd) ; 
for (nActiveVoice = 1 ;:nActiveVoice <= avers . 


nActiveVoicet+). 
¢ 
SetVoiceAccent (nActivevoice, 120, (128, 
S_NORMAL, 0) ; 
SetVoiceEnvelope (nActiveVoice, nActiveVoice, 
+ 100) ; 
SetVoiceQueueSize ABE CAVeUDTES 2 256) ; 
an - ., for C4 = O05 1 <5; itt) 
| SetVoiceNote CnActiveVoice, i: + 20, 8, 0) ; 
SetVoiceThreshold (nActiveVoice, 3) ; 
} 
syncatiVotces:, ©; 
StartSound() ; 


nTStatus = Got thresholdsts eas Omr 

TextOut (hDC, 0, 0, cBuf, wsprintf (cBuf, 
"Voices = Xd, Threshold Status = Oxax", 

nVoices, nTStatus)) ; 

vaitsoundstate (S_QUEUEEMPTY) ; 

TextOut (hDC, O, 20, cBuf, wsprintft (cBut, 
“ALL td voices done.", nVoices)) ; 

ReleaseDC (hwnd, hDC) ; 
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break ; 
case IDM_QUIT: 
Descroyeindoy ChWnd) >; 
break ; 
} 
break ; 
case WM_DESTROY: 
StopSound () ; 
' CloseSound 0’; 
; PostauitMessage (0) ; 
break ; 


/* stop application */ 


default: /* default windows message processing */ 


return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 


} 
return (COL) ; 


} 


SrarTSouND 


Purpose 
Syntax 
Description 


Returns 
See Also 


Parameters" 


Example 


eWin20 mWin30 w8Windl 
Starts playing all voice queues. 


int StartSound(void); 


‘This function is called after SetVoiceNote() i is used to put notes in one or more voice queues. All 


voices begin to play and will continue to play until either StopSound() is called, or all queues are’ 


- out of notes. 
"int, not used. 


StopSound(), OpenSound() 
None (void). 


This program fragment shows the typical usage of the StartSound() function. Elsewhere in the 
listing would be calls to StopSound() and CloseSound(). See the CloseSound() function descrip- 
tion for a more complete listing. 


if (OpenSound() > 0) 
C 


} 


SropSounp 


Purpose 
Syntax 
Description 


Uses 


Returns 
See Also” 
Parameters 
Example 


_ Stops the play process. 


SetVoiceQueueSize (1, 30) ; 
SetVoiceAccent (1, 120, 128, S_NORMAL, O) ; 
for (i =0 3 4<5-3 itt) 

SetVoiceNote ele, i+ 20, 8, 0) ; 


- StartSound() ; 


wWin2.0 m@Wind0 mWin3l 


int StopSound(void); 


Stops all notes playing on all voice queues. The contents of all voice queues are deleted and the 


sound driver shut down. - 


‘Used to interrupt the playing ofa ‘song. Typically, this is called by a user action, such as clicking a 


button or menu item. 
int, not used. 


~ StartSoundQ) 
_ None (void). 


See the example under the CloseSound() function description. 
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SyncALLVOICES (Requires sound device and sounddriver) § | mWin2.0 mWin30..mWin3l°° °° 

Purpose Synchronizes the timing of the playback of notes from several voice queues. 

Syntax . int SyncAllVoices(void); 

Description Each queue filled with note data by SetVoiceNote() is an ‘niopataet set of play data. Normally, : 
a you will want to force all queues to be played in time by calling SyncAllVoices(). 

Uses Used with sound devices that support more than one voice (multitimbral). This function will have 

no effect if the default SOUND.DRV driver is used to drive the PC speaker. 

Returns int, zero if successful. The function will return S_SERQFUL if one of the voice queue’s is full. 

See Also SetVoiceNote(), SetVoiceQueueSize() 

Parameters None (void). - 

Example See the example under the SetVoiceEnvelope() function description. 

WarrSounpSTATE (Requires sound device and sound driver) Win2.0_ mw Win3.0_ mWin3.1 

Purpose Prevents Windows from regaining conttol until one or more voice queues, passes a threshold 
state or is empty. . 

Syntax int WaitSoundState(int nState), 

Description Normally, control is passed back to Windows once StartSound() is called. The sound/music con- 
tinues while other Windows operations proceed normally. WaitSoundState() allows Windows ac- 
tivities to be halted until a specified state has passed, such as a certain number of notes 
remaining in a voice queue, or all | queues are haan 

Uses Not normally used. 

Returns int, zero if successful, S_SERDST if the State value is invalid. 

See Also SetVoiceThreshold() 

Parameters e-. . 

nState int: One of the states listed in Table 18-9. 


S_ALLTHRESHOLD ; 
S QUEUEEMPTY 
S_THRESHOLD 


‘Atty st stops unti all voices ae ees their threshold values, set with Stoica Trecho) 
Activity stops until all voice queues are empty (play complete). 


Activity stops until a voice queue passes its threshold value. In this case, WaitSoundState() 
should retum the voice number (driver dependent). , 


Table 18-9. WaitSoundState() Values. 


Example 


‘See the example under the SetVoiceThreshold() function description. 
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" Windows uses a different character set than DOS uses. This difference is not a big problem for English-speaking users, 
but it can be significant for users who work with other languages that use accented characters (French, German, 
Spanish, etc.). Understanding how Windows deals with the two character sets is the key to writing programs that will 
be directly portable to other languages. The Windows function library also includes several string manipulation func- 
tions. They are convenient and reduce the size of the programs you write because the executable code is stored in 
Windows’ dynamic link libraries. 


Character Sets : 
Windows uses the MS-DOS operating system to do file access. Ms. DOS us uses a character set which is commonly called 
the “IBM PC character set.” Windows politely refers to the IBM set as the “OEM character set.” As shown in Figure 19- 
1, the OEM character set includes a number of graphic symbols. These symbols date to the early days of the IBM PC, 
when most applications operated in character mode. The graphics symbo!s were used to draw lines for boxes and 
highlight areas. These symbols are unnecessary in a graphical environment like Windows. 

To read Figure 19-1, add the index on the top row to the index at the left side. For example, the code for a capital ; 
“A” character is 0x41, or 65 decimal. | 

The internal character set used by Windows is somewhat different. Windows refers to its internal set as the “ANSI 
character set.” ANSI is the American National Standards Institute. ANSI is an advisory board that works to coordinate 
standards on everything from computer languages (ANSI C) to shipping containers. ANSI works closely with non-USA 
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Hered 19-1. OEM Character Set. Figure 19-2. ANSI Character Set. 
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advisory boards, such as ISO (International Standards Organization), to come up with standards that apply interna- 
' tionally. The ANSI character set, which is displayed in Figure 19-2, is designed so that a text file in French transferred 
to a computer in Singapore will still display with the correct characters. 

’ If you compare the OEM and ANSI character sets, you will notice that the numeric digits and the alphabetical 
characters without accents have the same codes. The accented characters occupy different locations, and the ANSI 
character set contains a number of accented characters that are not present in the OEM set. The ANSI set also has a 

_ number of undefined character locations that show up as vertical bars when displayed. 

The differences between the two character sets becomes a problem when the user attempts to read a file created 
in DOS into Windows, or if the user runs a DOS program to access a file created by a Windows program. Even the file’s 
name can be a problem. For example, if a French-speaking user creates a file in DOS using the common accented “ S” 
character, the character will not be defined when viewed by a Windows program. This discrepancy occurs because the 
OEM code for “E” is 0x90, while the ANSI code for the same feller is OxC9.. 


Character Set Conversions 


To convert between the two character sets, Windows provides the OemToAnsi() and AnsiToOem() functions. These 
functions convert strings from one set of character codes to the other. AnsiToOem() converts a file name, input by the 
user of a Windows program, to the equivalent DOS file name. In cases where the OEM character set does not contain 
the same accented characters, the nearest equivalent OEM character is-selected. The presence of accented charac- 
ters causes some other problems. The standard C library functions, such as toupper() and tolower(), will not work 
properly under Windows because those functions assume the OEM character set. Windows provides alternatives for 
the most common character conversion functions. AnsiLower() and AnsiUpper() correctly convert ANSI strings from 
uppercase to lowercase and vice versa. Accented characters are correctly converted. Avoid the trap of built-in as- _ 
sumptions about the character set in use. For example, the following code fragment completely ignores accented 


characters. 
es /* WRONG EE! */ 
if (c >= 'A' 8&8 c <= 'Z' [| ¢ >= ‘at BBC <= 'z') 
/* do something */ ; 
The correct alternative to this incorrect example is to use the Windows functions IsCharAlpha() and IsChar- 
AlphaNumeric(). IsCharLower() and IsCharUpper() also process accented characters correctly for the ANSI charae- 


ter set. 


Fonts and Character Sets 


Although Windows uses the ANSI character set as its default, Windows programs can use different fonts. This font 
change commonly occurs in word processing applications, when the user has installed a new set of fonts for a printer. 
Because suppliers of printer fonts must support both Windows and non-Windows programs, the OEM character set is 
frequently used. This means that the character codes for accented characters within a document will change depend- 
ing on the font selected. The fonts will display the same character on the screen that is ultimately printed, as the 
supplier of the printer fonts also supplies the screen font drivers. 

When writing a Windows program, use a stock Windows font for user input and file name editing. Normally, the 
font is set in a dialog box or edit control, so there is no need to support printer fonts for these isolated bits of text. If 
your application supports multiple fonts, consider making a character assignment table available via a help screen. 
Doing so will save the user from a to dig up a listing of all of the character assignments for the font when an 
accented character i is used. . 


String Functions 


The Windows function library includes a number of convenient siting manipulation functions. The Serica in this 
book frequently use several of these. Istrlen() is used to determine a string’s length. Istrepy() is used to copy a string 
into a buffer, and Istreat() to add one string to the end of another. These functions have equivalents in the run-time 
function libraries supplied with C compilers. There are several reasons why you should use the Windows versions 
whenever ‘possible. 
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1. The executable versions of the Windows string functions reside in DLL (dynamic link library) files, If you U use 
these functions in your program, no additional code is added to your -EXE file. Using the compiler’ s library files. — 
“adds extra code to the end of your program, enlarging the .EXE file. 


2. The Windows versions of the string functions} process both short and long addresses. Using these functions avoids 
~ problems later if you switch a character string from local memory storage to a global memory block. 


3. The string comparison function Istrempi() (string comparison ignoring the difference between upper- aid lower- 
case letters) correctly processes accented characters for the ANSI character set. Using the C compiler library 
functions will cause odd behavior in sorting applications if the data has accented, characters. 


ae 


Character Set and String Function Summary 


Table 19-1 summarizes Windows character set and string functions. The detailed function descriptions are in me next 
section. 


AnsiLower Converts a character string to lowercase. 
AnsiLowerBuff Converts a character string to lowercase. 
AnsiNext . _ >” Moves to the next character in a string. 
AnsiPrev | 38 Moves to the previous character i ina string... 
AnsifoOem : eS Converts a string from the ANS! character set to the OEM character set. 
~. AnsifoOemBuff ‘Converts a character string from the ANSI to the OEM Gyaecley set. 
- AnsiUpper a ~ Converts a character string to uppercase... ek: 
~ AnsiUpperBuff. Converts a character string to uppercase. 
IsCharAlpha ee Determines whether an ANSI character is an alphabetical character. 
IsCharAlphaNumeric ° oe Determines whether an ANSI character i is an alphabetical or numeric character. 
IsCharLower - Determines whether an ANSI character is lowercase. : 
IsCharUpper ; ; Determines whether an ANS] character is an uppercase letter 
Istreat Adds one character string on to the end of another string.. eee 
Istromp . Compares. two character strings. ey a pre 
-Istrempi Compares two character eng ignoring the diference between uppercase and lowercase 
. letters. . ; 
Istrcpy _ Copies a character string to a memory buffer. ae 
Istrlen oe Determines the length of a character string. 
OemToAnsi . ~ Converts a character string from the OEM character set to the ANSI jeaciers set. 
OemToAnsiButt -. Converts a character string from the OEM character set to the ANSI character set. 
ToAscii eg - Converts from virtual key/scan code data to ANSI characters. 
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Table 19-1. Character Set and String Function Summary. 


: Character Set and String Function Descriptions ess 
This section contains the detailed a descriptions of the character set doe geting functions. 


7 “AnstLower ease foes Win 20 ein 30 mWindk | 
Purpose me “Converts a sting to lowercase: Pet 3 ee oo me 
oe "LESTE AnslLawer(LPST@ Giri) = oe 
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Description This function is the equivalent of the C library tolower() func- ener — 
* tion, except that accented characters are properly converted [RMN AlAs fee 
7 to lowercase. Do fa Quit | 
Uses To preserve special characters, this function should be used Original String: Ainé 
er ae for case conversion with the default Windows character set. After AnsiUpper: AINE _ 
Retums . _—-_ LPSTR, a pointer to the converted:string. If /pString contains - | After AnsiLower: ainé 
-. a single character, the returned value contains the converted After AnsiTo0en: aine 
character in the low-order byte. — Figure 19-3. AnsiLower() 
See Also AnsiUpper(), AnsiLowerBuff() Example. 
‘Parameters . 
lpString LPSTR: A pointer to a null-terminated character string, or to a single character. 
Notes The MAKEINTRESOURCE macro is convenient if a single character is being converted. For 
example, 
cnet “Cy 


= (charY (DWORD) AnsiLower (MAKEINTRESOURCE ('a')) ; 


Example This example, which is illustrated in Figure 19-3, converts the word “AINE” (meaning elder in 
7 French) to upper- and lowercase. The string is then converted to the OEM character set. 


Long FAR PASCAL wndProc HEHE hWnd, unsigned iNescage; WORD wParam, LONG UParan) 
{ Ls ; 


PAINTSTRUCT. spss 
char: oo eBut £1281, cTemp C15]; 

static char. Be? ie " c¢French Cj = (0x41, Oxee, Oxée, Oxe9, 0} a 

Sitch Cintessage) - , = _ : .. /® process windows.messages */ 


case wM_ PAINT: 
—_ Le et BeginPaint: ChWnd,. gps) , 
; Lstrepy (cTemp, French) ; 
Textout (ps.hdc, 10, 10, feuds wsprintf (cBuf,: 
ee “Original String: us", CLPSTR) ls ; 
AnsiUpper CcTemp) ; 
/ TextOut: (ps.hdc, 10, 30, cBuf, ‘wsprintf (cBuf, 
“After AnsiUpper: %s",_ CLPSTR) cTemp)) ; 
AnsiLower (cTemp) ; 
TextOut (ps.hdc, 10, 50, cBuf, wsprintf (cBuf, 
; “after AnsiLower: 4s", (LPSTR) cTemp)) ; 
AnsiToOem (cTemp, cTemp) ; , 
. SelectObject (ps.hdc, GetStockObject 
COEM_FIXED_FONT)) ; ; 
TextOut (ps.hde, 10, -70, cBuf, wsprintf (cBuf, 
“After AnsiToOem: %s", (LPSTR) cTemp)) ; 
EndPaint (hWnd, &ps) ; 


- break ; 
[Other program lines] _ . 
ANsILOWERBUFF : | —_Win20 we Win3.0 Wind 
Purpose § —-_—C Converts a character string to lowercase. 
Syntax WORD AnsiLowerBuff(LPSTR lpString, WORD nLength); 
Description _ ~ This function correctly converts the characters ina string to lowercase. Aceauiied characters are 
oa VSS properly converted to their lowercase equivalents. 
Uses. —~—-._. Can be used to eliminate capital letters in all, or part, of a string, 
Returns WORD, the length of the converted string. 
See Also AnsiLower(), AnsiUpperBuff() 
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_ Parameters, 
lpString 
nLength 


Example — 


LPSTR: A pointer to a character string to be converted to \eaiabonee, 


os WORD: The number of characters to convert. If aa is zero, the length is seeitnea to be 
- 65,586. 


This example, which is shown in Figure 19-4, uses AnsiUpperBuff() and AnsiLowerBuff() to con- 


_ vert the case of a character string. The first call capitalizes the entire string. Note that the ac- 


cented characters are correctly capitalized. Next, AnsiLowerBuff() is used to reduce characters 


-in the center of the string to lowercase. The last line demonstrates a programming error. The 


non-ANSI character conversion 
function strlwr(), from the C li- 
brary, is used to convert all the let- 
ters in the string to lowercase. Note 


; : WF og gine Same tatet go St gy Bea Cute Ce See saa 
se ee Oneness 4 7 


Dolt! Quit 


that the accented characters are 
ignored because the accented char- 
acters fall in the range of the graph- 


Original String: Special chars here: Ainé- 
AnsiUpperBuff: SPECIAL CHARS HERE: AINE § 
AnsiLowerBuff: SPEClal chars hERE: AINE | 


ics symbols for the OEM (IBM PC) 
character set, and they are not cor- 
rectly processed by strlwr(). Note 
how Istrlen() is used to pass the 
string length to AnsiUpperBuff() 
and AnsiLowerBuff(). 


Using strlwr: special chars here: ainE 


Figure 19-4. AnsiUpperBuff() and AnsiLowerBuff{) 
Example. 


tong FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
4 eae 


PAINTSTRUCT ps ; 


char 


static char 
static char 


switch CiMessage) 
€ 


cBuf £1281, cTemp [64] ; 
cStart £30] = ("Special chars here: "} ; 
cFrench CJ = (0x41, Oxee, Ox6e, Oxe9)} ; 


/* process windows messages */ 


case WM_PAINT: 

BeginPaint (hWnd, &ps) ; 

(strcpy (cTemp, eStart) ; 

tstrcat (cTemp, cfrench). : 

TextOut (ps.hdc, 10, 10, cBuf, wsprintf (CcBuf, 
“Original String: %s", (LPSTR) cTemp)) ; 

AnsiUpperBuff (cTemp, Istrlen (cTemp)) ; 

TextOut (ps.hdc, 10, 30, cBuf, wsprintf (cBuf, 
“AnsiUpperBuff: %s", (LPSTR) cTemp)) ; 

AnsiLowerBuff (cTemp +5, 10) >; | 

TextOut (ps.hdc, 10, 50, cBuf, wsprintf (cBuf, 

“AnsiLowerBuff: %s", CLPSTR) cTemp)) ; 

strlwr CceTemp) ; /* wrong !!! */ 

TextOut (ps. hde, 10, 70, cBuf, wsprintf (cBuf, 
“Using strlwrs %s", CLPSTR) STeAp?) 7 

EndPaint ChWnd, &ps) ; 


break ; 
| [Other program lines] 
ANSINEXT eWin2.0 wWin30 wWin3.1 
Purpose i _ Moves to the next character in a string. 
Syntax LPSTR AnsiNext(LPSTR [pCurrentChar); 
Description This function is required only if the application will use character sets that require more than 


one byte per character (for example, the Japanese character set). AnsiNext() will move to the 


. hext character position, regardless of the number of bytes required. 
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Returns 
. been reached. 
See Also AnsiPrevQ) 
Parameters 
_[pCurrentChar _LPSTR: A pointer to the current 
—- - character in a character string. 
Example This example, which is shown in 


Figure 19-5, uses AnsiNext() and 
AnsiPrev() to move to different lo- 
cations in a character string. These 

. functions are not required for the 
character set in Figure 19-5 (the 
ANSI character set), as only one 
byte is required per character. 
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_LPSTR, a pointer to the next character i in the string. Returns NULL if the énd of the string has 


generic’: 


sie aa ey PEL vay eat AT : . 
ae Gun Stated t 

NTS Sa : Tene . ae ‘ 

ww By : 7 


Original String: Special chars here: Ainé 
Character 21 =1 
Character 21-5 =r 


Figure 19-5. AnsiNext() and AnsiPrev( ) Example. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
: 


PAINTSTRUCT ps ; 
char 
static char 


static char - cFrench CJ = 
LPSTR tpStr ; 

int 4G 

char c: 


switch (CiMessage) 
{ 


case WM_PAINT: 


BeginPaint (hund, &ps) ; 
lstrcpy (cTemp, eStart) ; 


cBuf [1281], cTemp [64] ; 
cStart £30] = {"Speciat chars here: "} ; 


{0x41, Oxee, Oxé6e, Oxe9} ; 


/* process windcws messages */ — 


istrcat (cTemp, creanehi 


LpStr = (LPSTR) cTemp ; 


TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
ocisinat String: is", LpStr)) ; 


for (§=0; 1< 21; 


s i+t) 


LpStr = AnsiNext (lpsStr) ; 
TextOut (ps.hdc, 10, 30, cBuf, wsprintf (cBuf, 
“Character 21 = %c", *lpStr)) ; ; 


for (Gi =O; 1<5; 


i++) 


UpStr = AnsiPrev (cTemp, lpStr) ; 
TextOut (ps.hdc, 10, 50, cBuf, wsprintf (cBut, 
“Character 21 - 5S = %c", *lpStr)) ; 


EndPaint (hind, &ps) ; 


@Win3.!} 


break ; 
[Other program lines] 
ANSIPREV mWin2.0 mWin3.0 
Purpose Moves to the previous character in a string. 
Syntax LPSTR AnsiPrev(LPSTR [pStar/, LPSTR [pCurrentChar); 
Description This function is only required if the application will use character sets that require more than 
one byte per character (for example, the Japanese character set). AnsiNext() will move to the 
previous character position, regardless of the number of bytes required. . 
Returns LPSTR, a pointer to the previous character in the string. Returns IpStart if lpCurrentChar points 
. to the start of the string. 
See Also AnsiNext() . 
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Parameters 


lpStart LPSTR: A pointer to the beginning of the character string. “4 
lpCurrentChar _ LLPSTR: A poirver vo the current character in a character string. 
Example See the previous example under AnsiNext(). 
AnsIToOEM 7 ; mWin2.0 mWin30 mWin3.l 
Purpose Converts a string from the ANSI character set to the OEM character set. —— 
Syntax int AnsiToOem(LPSTR lpAnsiStr, LPSTR lpOemStr); = . 
Description This function does a direct conversion of the characters. If an equivalent character exists in the 
OEM character set, that character i is selected, The string can he longer than 64K. 
Returns » int, always —L. a 
See Also OemToAnsi() _ 
Parameters 
lpAnsiStr LPSTR: A pointer to a null-erminated ANSI character string to be converted. . 
lpOemStr LPSTR: A pointer to a character buffer that will contain the translated characters. The buffer 
must be at least as long as the string in the buffer pointed to by /pAnsiStr. ipOemStr can be the 
same as bpAnsiStr, In this case, the string is converted in place. 
Example See the emai under the AnsiLower() function description. 
AnsiToOrmBure —mWin2.0  wWin30  @Win3.l 
Purpose Conv erts : a character vee from the ANSI to the OEM character set. 
Syntax void AnsiToOemBulf(LPSTR (pAnsiStr, LPSTR IpOemStr, int nLength); 
Description - This function converts characters from the default Windows ANSI character set to the OEM (BM 
PC) characters. Accented characters are converted to the nearest alternative. 
Uses ~ AnsiToVemBulf() is useful for converting strings that are not null- terminated. AnsiToOem() i is 
simpler to use for null-Lerminated strings. 
Returns — No returned value (void). 
See Also AnsiTo( fem() 
Parameters 
lpAnsiStr LPSTR: A pointer to an ANSI character ie tobe converted. The string ‘oes not have to be null- 
terminated, 
lpOemStr LPSTR: A pointer to a character 
buffer that will contain the trans- : gen ec. 
lated characters. The buffer must i 
be at least as long as the string in Do tt!__Quit —— 
the buffer pointed to by IpAnsiStr, ANSI String: Special chars here: Ainé ane 
fpOemStr can be the same as OEM String: Special chars here: ewan’ 
IpAnsiStr, In this case, the string is is = Figure 19-6. AnsitToOemBuff() Example. 
converted in place, 
nbength WORD: The nutuber of characters to be converted, — 
Example This example, which is itlustrated in Figure 19-6, converts an ANSI character string to OEM char- 


acters, so that the characters are properly displayed when the OEM_FIXED_FONT is selected. 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned Teesnaey WORD wParam, LONG lParam) 
{ : 


PAINTSTRUCT ps; 

char cBuf £128], cANSI [64], cOEM [64] ; 
static char cStart £30] = {"Special chars here: "} ; 
static char cFrench CJ = (0x41, Oxee, Ox6e, Oxe9} ; 


switch (iMessage) 
{ 


See Also 


/* process windows messages */— 


case WM_PAINT: 

BeginPaint (hWnd, &ps) ; 

lstrepy (cANSI, cStart) ; 

Lstrcat (cANSI, cFrench) ; 

TextOut (ps.hdc, 10, 0, cBuf, seorunet (cBuf, 
“ANSI String: %s", (LPSTR) cANSI)) ; . 

‘AnstToOemBuff CcANSI, cOEM, 1 + Lstrlen (CANSI)) ; 

SelectObject (ps.hdc, GetStockObject (OEM_FIXED_FONT)) ; 

TextOut (ps.hdc, 10, 20, cBuf, wsprintf (cBuf, 
"OEM String: %s", C(LPSTR) cOEM)) ; 

EndPaint (hWnd, &ps) ; 


break ; 
[Other program lines] 
AnsIUPPER meWin20 .@Win3.0 mWin3.1 
Purpose Converts a character string to uppercase. 
Syntax LPSTR AnsiUpper(LPSTR /pString); 
Description This function is the equivalent of the C library toupper() function, except that accented charac- 
. ‘ters are properly converted to uppercase. 
Uses. To preserve special characlersl this function should be used for case conversion with the default 
Windows character set. 
Returns LPSTR, a pointer to the converted string. If IpString contains a single character, the returned 
_ value contains the converted character in the low-order byte. 
See Also AnsiLower(), AnsiUpperBuff() 
Parameters | 
lpString LPSTR: A pointer to a null-terminated character string, or a single character. . 
_ Notes The MAKEINTRESROUCE macro is convenient if a single character is being converted. For ex- 
ample, 
| 
char Cc; 
c = (char) (DWORD) AnsiUpper (MAKEINTRESOURCE ('a')) ; 
Example See the example under AnsiLower(). 
AnsIUpPpERBUFF | | gWin20 mWin30 mWin3.1 
Purpose Converts a character string to uppercase. ; 
Syntax ” WORD AnsiUpperBuff(LPSTR /pString, WORD nLength); 
Description - This function correctly converts the characters in a string to uppercase. Accented characters are 
- . properly converted to their uppercase equivalenis. 
Uses Can be used to eliminate the lowercase letters in all, or part, of a string. 
Returns WORD, the length of the converted string. 
AnsiUpper(), AnsiLowerBuff() 
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Paramevers . ae: 

lpString LPSTR: A pointer to a character string to be converted to uppercase. 

nLength _ WORD: The number of characters to convert. ; 

Example _ See the example under AnsiLowerBuff(). 

IsCHARALPHA. | — Win2.0 sw Win3.0- @Win3.1 

Purpose Determines whether an ANSI character is an alphabetical character. — 

Syntax BOOL IsCharAlpha(char cChar); 

Description This function.determines whether eChar i is Seer Accented characters are correctly pro- 
cessed. 

Returns BOOL. TRUE if the character is alphabetical, FALSE if not. Ee oveAnineneleti noe 

See Also IsCharAlphaNumeric() . ; 

Parameters . | String: ; 

cChar char: The character to test. ponent ven : d : + 


Example This example examines each character of an ANSI character eee 000100001 
ee string, as shown in Figure 19-7. Note that the IsChar... func- oS 

tions correctly process accented characters in both upper- and Figure 19-7, ics ) 
lowercase. - Example. 


Long FAR-PASCAL WndProc CHWND hWnd, unsigned iwewanae: WORD wParam, LONG {Paran) 
{ 


PAINTSTRUCT ps ; 

char _ cBuf £128] ; 

static char cFrench CJ = S 0x37, Ox3e, 0x20, 0x41, Oxee, 
Oxé6e, Oxe9, 0x20, Oxe1, 0) ; 

int i; ; 

switch (iMessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint \hund, &ps) ; 
TextOut (ps.hdc, 10, 0, ““string:", 72-3 
“TextOut (ps.hdce, 10, 15, "Alphas", 6) ; 
TextOut (ps.hdc, 10, 30, "AlphaNum:", 9). ; 
TextOut (ps.hde, 10, 45, “Lower:", 6) ; 
TextOut (ps.hdce, 10, 60, “Upper:", 6) ; 
for (i =0; , < strlen “CeFrench) ; wee 
{ ; 
té tout (ps.hde, 100 + C4 * 10), 0, eBuf, 
aeneanet (cBuf, Nac", cFrench Cid) ; 
TextOut (ps.hdc,'100 + (i * 10), 15, cBuf, 
wsprintf (cBuf, "211i", 
CARGHerALDNS. CoFrench Cid) 
71:0))9); 
TextOut (ps.hdc, 100 +. Ci * 10), 30, cBuf, 
wsprintf (cBuf, "X1i", 
(IscharalphaNuneric CcFrernch: id 
2.4 ::0))); 
TextOut ae hde, 100 + (i * 10), 45, cBuf, ‘: 
sprintf CcBuf, "4173", 
(IsCharLower <cFrench CiJ)> 
- 21:00); 
. TextOut:(ps.hde, 100 + (i * 10), 60, cBuf, : 
wsprintf (cBuf, "421i", 
- ; (IscharUpper CoFrench Cil>- 
21:00); a 
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EndPaint ChWnd, &ps) ; 


break ; 
[Other program lines] 
isCuaRALPHANUMERIC mWin20 om Win30) mWin3l 
Purpose Determines whether an ANSI character is an alphabetical or numeric character. 
Syntax BOOL IsCharAlphaNumeric(char cChar); 
Description This function determines whether cChar is an “re character or a numerical digit. Ac- 
cented characters are correctly processed. j 
Returns BOOL. TRUE if the character is alphanumeric, FALSE if not. 
See Also IsCharAlpha() 
Parameters 
_ eChar char: The character to test. 
Example See the example under the IsCharAlpha() function description. - 
IsCHaRLowER @Win20 mWin30 mWin3.1 
Purpose Determines whether an ANSI character is lowercase. — 
Syntax BOOL IsCharLower(char cChar); 
Description This function determines whether cChar is a lowercase alphabetical character. Accented char- 
‘ acters are correctly processed. 
Returns BOOL. TRUE if the character is an uppercase alphabetical character, FALSE if not. 
See Also IsCharUpper() _ 
Parameters 
cChar ‘char: The character to test. 
Example See the example under the IsCharAlpha() function description. 
IsCuarUprer —mWin2.0  m@Win3.0 = mWin3t 
Purpose Determines whether an ANSI character is an uppercase netie 
Syntax . BOOL IsCharUpper(char cChar); ~ : 
Description This functidn determines whether cChar is an uppercase aeneis character. Accented char- | 
acters are correctly processed. 
Returns BOOL. TRUE if the character is an uppercase alphabetical character, FALSE if not. 
See Also IsCharLower() 
Parameters : 
cChar- char: The character to test. 
Example i - See the example under the IsCharAlpha() function description. 
- LSTRCAT eWin2.0 wWin30 wWin3.1 
Purpose Adds one character string to the end of another string. . 
. Syntax LPSTR Istreat(LPSTR lpString1, LPSTR lpString2); 
Description The function name is short for “long string concatenation.” Istreat() searches the string pointed © 


to by lpString! for the first null character. The string pointed to by /pString2 is copied into 
lpString! starting at that point. All strings must be less than 64K in length. This function is 
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Uses 
Returns . 
See Also 


Parameters 
lpString1 


lpString2 


_ Example 


enuivalent to the standard C library fiction streat(), except that it uses far pointers. Near point 


__ ers will automatically be converted to far pointers by the compiler. 


Frequently used to build composite character strings, such as vas messages that contain a 
file name, or to add a file name to file path. .. 


LPSTR, a pointer to /pString1. This will be the start of the satined: atelitg Returns zero On 
error. . 


Istrepy(), Istremp(), stem) 


LPSTR: A pointer to the destination character array. The string iia to by ipString2 will be 
copied to the end of lpString/, starting at the first null character. The character array or memory 
buffer pointed to by lpString/ must be large enough to hold the combined strings. The string i in 

lpStringI must be null-terminated. 


LPSTR: A pointer to the charac string to be ae to the end of ipStringl. The string must be 
null-terminated. 


This example shows a typical use of the string copying and concatenation functions. Text i is Cop- 

ied into a global memory block, allocated with GlobalAlloc(). First, the cBegin string is placed in 
the memory block. Then.the cFrench string (consisting of some accented characters) is added 
with Istrcat(). When the text is needed for the WM_PAINT message processing, the block is 
locked. The address of the memory block is then a far pointer to 4 string. The memory block is 
released after use. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG \Param) 
4 . i 


PAINTSTRUCT ps ; 

char © , cBuf C1281; 

static char : cBegin [J] = ‘Cstarting Text. "} ; 

static char . cFrench CJ = {0x41, Gree, OSes: Oxe9, 03 | 
static HANDLE | hMem ; 

LPSTR _UpMem ; 

. switch CiMessage) ; /* process windows messages */ 

% { ‘ . 


case WM_CREATE: 


hMem = GlobalALloc (GHND, 64) 5 
LpMem = GlobalLock ChMem) ; 
Lstrcpy (lpMem, cBegin) ; 
Lstrcat (LpMem, cFrench). : 
GlobalUnlock (hMem) ; 
; break ; 

case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
lpMem = GlobalLock (hMem) ; 
TextOut (ps.hdc, 0, Oe pen, Lstrlen (lpMem)) ; 
GlobatUnlock (hMem) ; 
EndPaint chNnds &ps) ; 


break ; 
case WM_ COMMAND: /* process menu items */ 
switch (wParam) 5 
{ 
case IDM_QUIT: /*, Send end of appyieatien message */ 
DestroyWindow ChWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: ; /* stop application */ 


GlobalFree ChMem) ; 
PostQuitMessage (0) ; 
break ; 
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: /* default windows message processing */; 
return DefWindowProc “Chiind, iMessage, NEBr ORs (Param) ; 


} 
return COL) ; 


} 
LSTRCMP wWin20 3 mWin30 mWin31 
Purpose Compares two character strings. 
Syntax int lstremp(LPSTR [pString1, LPSTR lpString2); 
Description  _—_This function determines which of the two strings would come first in the dictionary. The deter- 
mination is based on the language installed in Windows. The comparison is case sensitive, with 
capital letters coming before lowercase letters. 
The strings must be smaller than 64K bytes long. The result of the comparison may not be the 
- same as would be returned by the C library function stremp(, as accented characters are cor- 
rectly processed only by Istremp(). 
- Uses Used in determining the sort order of strings in database applications. Often used to Se check 
if two strings are identical. 
Returns int, 0 if the strings are identical. Negative ifipString! would come before IpString? in the dictio- 
nary. Positive if lpString1 would come after lpString2. ; 
See Also Istrempi() 
Parameters 
lpString! LPSTR: A pointer to the first null-terminated character string. 
lpString2 LPSTR: A pointer to the second null-terminated character string. 
Example The example shown in Figure 19-8 compares two strings. Both of the strings contain the same 


letters; although, the second string has a a word. Bere) detects this, and returns 1, 
as the lowercase letters in the first : eae 
string would come after the up- 
percase letters in the second. 
Istrempi() finds the two strings 
equal, and returns 0. Istrlen() de- 
termines the length of a string. The 
returned length of 11-characters - 
does not include the terminating 
NULL character. Figure 19-8. Istremp() Example. 


gene THE. 


Do It! = ae | 


trings: 1] Test String | 2) Test STRING | 


istrcmp = 1 


ake FAR PASCAL wndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
PAINTSTRUCT \ ps aoe 
char s CBU £128] ; 
static hak —— cString1 C7 = {"Test String} ; 
static char _eString2 £ ge a STRING") ; 
int nN; 
oereen CiMessage) /* process windows messages */ 
case WH_PAINT: 
: BeginPaint -ChWnd, &ps) ; 
TextOut (ps.hdc, 0,0, cBut, usprintt CeBut ; 
“Strings: 1) %s 2) %s", 
CLPSTR) cString1, CLPSTR) eString2)) ; 
n=. Lstremp (cStringt, cString2) ; 
- TextOut (ps.hdc, 0, 15, cout wsprintt ‘(cbuf, oe 
“Lstrcap = ud", YG ig ME ce 
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[Other program lines] — 


Purpose - 


Syntax 
Description 


Uses 
| Returns 


See Also 
Parameters 
lpString! 
lpString2 
Example 


LSTRCPY 
Purpose 
Syntax’ 
Description 


Uses . 
Returns 
See Also 


LSTRCMPI 


Parameters. 


lpString! 


IpString? 
Example 


n= Lstrempi (cStringt, cString2) ; ; 
TextOut (ps.hdc, 0, 30, cBuf, wsprintf (cBuf, 
“Uistrempi = %d", n)) ; 
n= lstrlen (cString1) ; 
{ TextOut (ps.hdc, 0, 45, cBuf, wsprintf (cBuf, 
“Lstrlen = %d", nd) 7 
-EndPaint ChWnd, &ps) ; 
break ; 


1 
! 


Bi Win 2.0 Win 3.0 Win 3.1 
Compares two character strings, ignoring the difference between uppercase and lowercase let- 
ters. — . 

int Istrempi( LPSTR [pString1, LPSTR lpString2); 

This function determines which of the two strings would come first in the dictionary. The deter- 
mination is based on the language installed in Windows. The comparison is not case sensitive. 
Capital letters are treated the same as lowercase letters. The strings must be smaller than 64K in 
length. The result of the comparison may not be the same as would be returned by the C library 
function strempi(), as accented characters are correctly processed only by Istremp(). 

Used in determining the sort order of strings in database applications. Often used to simply check 
whether two strings of identical upper- and lowercase letters are equivalent (filenames). 
int, 0 ifthe strings are identical. Negative, if /pString! would come before [pString2 in the dictio- 
nary. Positive, if lpStringI would come after lpString2. 


Istremp(), Istrcat(), Istrepy(), IstrlenQ() 


Q 


LPSTR: A pointer to the first null-terminated character string. 


; LPSTR: A pointer to the second null-terminated character string. 


See the previous example under the Istremp() function description. 


| Win2.0 mWin30 sWin3.1 
Copies a character string to a memory buffer. | 
LPSTR Istrepy(LPSTR lpString1, LPSTR ipString2), 
The function name is short for “long string copy.” Istrepy() copies all of the characters including 
the terminating NULL character in the buffer pointed to by /pString2, into the buffer pointed to 
by [pString1; All strings must be less than 64K in length. This function is equivalent to the stan- 
dard C library function strepy(), except that it uses far pointers. Near pointers are automatically 
converted to far pointers by the compiler. 


Used to put character strings in local and global memory buffers. Frequently used with Istreat(). 
LPSTR, a pointer to /pString!. Returns zero on error. oo 
IstreatQ) . . 


LPSTR: A pointer to the destination character array. The string pointed to by [pString2 will be 


_ copied to the beginning of /pString!. The character array or memory buffer pointed to by 


ipString1 must be large enough to hold lpString2. 
LPSTR: A pointer to the character string to be copied to IpString!. 
See the example under the Istrcat() function description. 


N 
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LSTRLEN 


Purpose 
Syntax 
Description 


Uses 


N 


Returns 


Parameters 
lpString 
Example 


OemMTOoAnsI 
Purpose 

Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
lpOemStr 


lpAnsiStr 


Example 


{ . 
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wWin2.0 eWin30 mWin31 


_ Determines the length of a character string. 


int Istrlen (LPSTR lpString); 


The length returned does not include the terminating NULL chuactar Be sure to allocate an 
extra byte for the NULL character is Istrlen() if being used to size a memory space to hold a null- 
terminated character string. The string must be smaller than 64K in length. 


Frequently used within other functions to pass the character string length as a parameter. For 
example, inside TextOut() 


char cBuf C3 = 
TextoOut (hdc, 10, 


{"Some Text."} ; 
10, cBuf, ieteien (cBuf)) ; 


In this case, Istrlen() is used to pass the number of characters in the cBuf// buffer to TextOut(). 
int, the number of characters in the buffer pointed to by [pString. 


LPSTR: A pointer to a null-terminated character string. 
See the examples under the AnsiLowerBuft() and Istremp() function descriptions. 


wi Win 2.0 ta Win 3.1 
Converts a string from the OEM character set to the ANSI character set. 

int QemToAnsi(LPSTR [pOemStr, LPSTR lpAnsiStr); 

This function does a direct conversion of the characters from the OEM (IBM PC) character set to 
the default Windows character set (ANSI). If an equivalent character exists in the ANSI charac- 
ter set, that character is selected. If no equivalent exists (graphics characters), the nearest 
match is chosen. The string can be longer than 64K. 

This function is needed if strings captured in the DOS environment are to be displayed in Win- 
dows using the default ANSI character set. 


& Win 3.0 


int, always - =. 
OemToAnsiBuliQ), AnsiToOem() 


LPSTR: A pointer to a null-terminated character string containing OEM characters. 
LPSTR: A pointer to a character buffer that will contain the converted characters. ieilaaalee can 
be the same as [pOemStr, which causes the string to be con- i zs 
verted in place. 

This example, as shown in Figure 19-9, demonstrates two dif- 
ferent stock fonts. The upper string ic written with the OEM 
font. The characters must be converted to the ANSI character 
set before the buttom line ean be written using the ANSI fixed- 
pitch stock font. 


iSvord in French: Epée 


Figure 19-9. OcmToAnsi( ) 
Example. 


long FAR PASCAL WndProee (HUND hind, unsigned iMessage, WORD wParam, LONG tParam) ° 


PAINTSTRUCT ps; 


char 


static char 
Static char 


switch CiMessage) 
{ : 


cSuf C128) ; 
eString1 C1 = ("Sword in French: "} ; 
eString2 CJ = (0x90, 0x70, 0x82, 0x65, 0} ; 


/* precess Windows messages */ 


. ri 
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case WA_PAINT: ; 
BeginPaint (hWnd, &ps) ; . 
Ustrepy (cBuf, cString1) ; 
istreat (cBuf, cString2) ; 
SelectObject (ps.hdc, GetStockObject COER_| FIXEO_ PONY? 2 
TextOut (ps.hdc, 0,.5, eBut, istrlen (cBuf)) ; 
OemToAnsi (cBuf, cBuf) ; /* in-place conversion nf 
SelectObject (ps. hdc, GetStockObject CANSI_FIXED_FONT)) ; 
TextOut (ps.hdc, 0, 20, cBuf, lstrlen (cBuf)) ; 


EndPaint (hWnd, Spa) ¢ . I: 
: break ; | : n OS ; 2 & 
[Other program lines] — 
OrmMToANsIBUFF _ -_ eWin20 mWin30 mWin3l 
Parpose  -_— Converts a character string from the OEM character set to the ANSI character set. 
Syntax void OemToAnsiBuff(LPSTR /pOemStr, LPSTR lpAnsiStr, int nLength); 
Description | This function is identical to OemToAnsi(), except that the number of characters to convert can 


be specified. OemToAnsiBuff() docs a direct conversion of the characters from the OEM (IBM. 
. PC) character set to the default Windows character set (ANSI). If an equivalent character exists 
_ in the ANSI character set, that character i is selected. If no equivalent exists (graphics charac- 
ters), the nearest match is chosen. 


Uses Used in place of OemToAnsi() when the string to be converted is not null- terminated, 


Returns §  —S— No returned value (void). _ 
See Also OemToAnsi(), AnsiToOem() 
Parameters ae a: es 
lpOemStr © LPSTR: A pointer to a character string containing OEM characters. 
lpAnsiStr ’ LPSTR: ‘A pointer to a character buffer that will contain the converted characters. lpAnsiStr can. 
be the same as /pOemStr, which uses the string to be converted in place. 
: nLength int: The number of characters in /pOemStr to convert, 
Example o This example produces the same results as the | previous example under OemToAnsi(). In this 


case, the conversion to the ANSI character set is accomplished with OemToAnsiBuff(). 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
t . . 


PAINTSTRUCT ps; 

char cBuf £1281, cBuf2 £128) ; 

static char cStringi CI = {"Sword in French: "} ; 

‘static char cString2 CJ = (0x90, 0x70, 0x82, 0x65, 0} ; 
switch CiMessage) : ae process Windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
(strepy (cBuf, eString! ; 
lstrcat (cBuf, cString2) ; 
_ OemToAnsiBuff (cBuf, cBuf2, Lstrlen (cBuf)) ; 
SelectObject (ps.hdc, GetStockObject COEM_FIXED_FONT)) ; 
~ TextOut (ps.hdc, 0, 5, cBuf, lstrlen (cBuf)) ; 
SelectObject (ps.hdc, GetStockObject (ANSI_FIXED_FONT)) ; 
TextOut (ps.hdce,-0, 20, eBuf2, pteanten <cbute2? : 
EndPaint ChWnd, &ps) ; f ~ 
break ; 


| [Other program lines] 
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ToAsci 


Uses 
Returns 


See Also 


Parameters 
wVirtKey 


wScanCode 
IpKeyState 


lpChar 

wFlags . 

Related Messages 
Example 
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. mWin2.0 @Windd Wind.) 
Converts virtual key/scan code data to ANSI characters. 
int. ‘ToAscii(WORD wVirtKey, WORD waSeanCode, LPSTR ipKeyState, LPVOID lpChar, WORD 
wFlags); 


Mainly used with internaticnal (non-USA) peters ne The function reads the virtual 
key, scan code, and key state data, and then puts the translated ANSI character equivalent into 
the buffer pointed to by /pChar. . 


"Useful in processing accent characters. 
- int, the number of bytes copied to the [pChar buffer. Two for accent or dead-key characters that 


do not have an ANSI value. One for direct translation to an ANSI character. Zero if no translation 
was possible. 


. ema; AnsiToOem() 


WORD: The virtual key code, This is the wParam value used when processing a WM_KEYUP cr 
WM_KEYDOWN message. 


WORD: This is the OEM scan code. Bytes 16 to 23 of lParam contain this value when processing 
a WM_KEYUP or WM_KEYDOWN message. 


LPSTR: A pointer to a 256-byte array containing the current status of all virtual keys. Use 
GetKeyboardState () to initialize this array prior to calling ToAscii(). 


LPVOID: A’pointer to a 32-bit buffer (DWORD) that will hold the translated character. 
WORD: The bit 0 flag's setting. Set to NULL. 
WM_KEYDOWN, WM_KEYUP . 


This example uses ToAscii() to convert the WM_KEYDOWN parameter data into its ANSI charac- - 
ter equivalent. Every time a key is pressed, the number of translated bytes (usually one) and the 


ANSI character are displayed in the program's client area. 
tong FAR PASCAL WndProc CHWND hind, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC hoc ; 

char cKeyBuf (2563, cBuf [10] ; 

DWORL duAnsiValue ; 

int nCharResult, nScanCode ; 

‘switch CiMessage) /* process windows messages */ 

case WM_KEYDOWN: ; 
» InvalidateRect Chuind, NULL, TRUE 7 /* clear client area */ 
UpdateWindow enw) 2 
hOC = GetDC ChWnd) ; : i 
nScanCode = Clpacse >> 16) & Ox00ff ; /* get scan code */ 
’ GetKeyboardState (cKeyBuf) ; /* read all 256 VK_ values */ 
nCharResult = ToAscii (wParam, nScanCode, cKeyBuf, 
SduAns Value, NULL) ; 
itoa (nCharResult, cBuf, 10) ; 
TextOut (hdc, 10, 10, cBuf, strlen (cBuf)) ; 
TextOut (hdC, 50, 10, "= bytes ToAsciil) vateliod: ", 27) 3 
cBuf [OJ = (char) (dwAnsiValue & OxOOff) ; 
TextOut (hdc, 10, 30, cBuf, 1)-; — 
TextOut Choc, 50, 30, "= ASCII char.", 13) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
[Other program lines] 
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Windows uses the MS-DOS disk file functions. Prior to Windows 3.0, the use of MS-DOS was obvious to the Windows 
programmer as only the OpenFile() function was provided for file access. The MS-DOS file functions from the C 
compiler’s run-time library were used to read and write data. The Windows function library included functioncalls to 
the lower-level DOS functions, but these were “undocumented” functions. The function names were preceded by an 
underscore character to emphasize their temporary nature. With the release of Windows 3.0, the file functions have 
been legitimized. The Windows function library now includes the previously “undocumented” functions. The under- 
score characters in front of the function names have been retained for compatibility with previous versions. 

You are most likely to run into the differences between the OEM character set used by MS-DOS and the ANSI 
character set used by Windows when using file functions. All of the file functions available within Windows do the 
conversion from ANSI to OEM characters for you. If you access the MS-DOS file or path name data directly (perhaps 
using the OFSTRUCT data filled by the OpenFile() function), keep in mind that the file names and path names will 
contain OEM characters. 

Windows includes excellent support for maintaining initialization files, such as WIN.INI. These files are read on 
startup, and provide information to the program concerning how the user left the application when it was last run. 
Typically, they are used to remember window sizes and locations, default file names, and preferred color combina- 
tions. 


Disk Files 


From the point of view of an application program, a disk file is just a series of nets values. There is no automatic 
structure to the data. An application writes the.data to the file in any arbitrary order. This might be a series of integers 
(two-byte values) followed by string data (one byte per character). When the data is read back from the disk, the 
application must know the order in which the data was written in order to make sense out of the individual bytes. 
Before any action on a disk file can be taken, the file must be opened. Opening the file alerts MS-DOS that the file 
will see activity. MS-DOS uses an unsigned integer value, called a “file handle,” to keep track of the open files. Only a 
limited number of files can be open at one time (determined by the FILES environment variable in DOS). Files should © 
be closed as soon as possible after use. 
Within Windows, the preferred way to open or create a new file is with the OpenFile() function. A typical call to 
CpenFile() is as follows: 
int hFileHandle ; 
OFSTRUCT of ; 


hFileHandle = OpenFile ("MYFILE. TMP", &of, OF_CREATE) ; 


This example creates a file called MYFILE.TMP on the default directory. Because of the OF_CREATE flag, the file 
is opened and truncated to zero bytes of data if the file already exists. The file handle is returned by OpenFile(). The 
file handle is an integer. The file handle is used by all of the data reading and writing functions. 

OpenFile() uses a data structure called OFSTRUCT, that is defined i in WINDOWS.H as pb: 


typedef struct tagOFSTRUCT 
t 


BYTE cBytes; , /*® Length of OFSTRUCT */ 
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BYTE fFixedDisk; /* non-zero if fixed drive */ 

WORD nErrCode; /* MS DOS error code */ 

BYTE reserved[4]; /* file date and time */ 

BYTE szPathNamel128]; /* full path name and */ 

/* file name COEM chars) */ 
} OFSTRUCT; 

typedef OFSTRUCT . *POFSTRUCT; 
typedef OFSTRUCT NEAR *NPOFSTRUCT; 
typedef OFSTRUCT FAR *LPOFSTRUCT; | 


~ This data is filled in every time OpenFile() is called. 2 
An alternative to using OpenFile() is to used the lower-level file functions like _lcreat() and _lopen(). They do 

the specific jobs of creating new files and opening existing ones. OpenFile() is-more versatile, and generally pre- 
ferred. When the file is open, the low-level file access functions _lread(), _lwrite(), and _llseek() are used to read, 
write, and move to data in the file. These functions are direct calls to their MS-DOS function equivalents. As soon as 
the need for the file’s data.is complete, the application must call _lclose() to close the file. Failing to close a file risks 


losing the file’s data after the application terminates. 


Lists of File Names 
Most applications need to allow the user to select-a file | Open F File Name: 
from a list of files on a certain directory. This task is so 
common that Windows provides automatic functions for 
filling list boxes and combo boxes with a specified direc- | 
tory list. The list box or combo box must be insideadia- § Filesin  c:\...\samples\fileopen 
log box. DigDirList() fills a list box with a set of file 
names specified by an MS-DOS search string like “*.TXT” 
. .(show every file on the directory with the TXT exten- 
sion). DlgDirListComboBox() does the same function for 
a combo box. (A Cancel o- 

When the list of files is added to the list or combo ; meena 
box, related directory and drive names are included in 
the list surrounded by square brackets. A typical ex- ; 
ample is shown in Figure 20-1. Figure 20-1. Files Listed in a List Box. 

The Windows Software Development Kit (SDK) pro- 
vides an excellent example program called OPENFILE. Figure 20-1 shows the file selection dialog box that this ex- 
ample program creates. Extract the dialog box definition and dialog box function from this file and use it in any 
application requiring file selection. 


Initialization Files : 


A common problem for many programs is “remembering” settings from the last time a user ran the application. Many 
applications store the main window's size and location, color selections, most recently opened file names, and other 
common data for the next session. Prior to Windows 3.0, all of this initialization data was stored in a single file called 
WIN.INI. WIN.INI includes initialization information used by Windows, and specialized information written and ac- 
cessed by other applications. The WIN.INI file is located in the Windows subdirectory, the trey that contains 
WIN.COM. A typical excerpt from WIN.INI is shown below. 


CWindows Help 
Maximized=0 
X1=59 

Yu=54 

Xr=666 

Yd=683 


‘Inthis case, the Windows Help application stores information about the size and location of the help window the 
last time Help was called. 
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Applications can write new entries to WIN.INI using WriteProfileString(). This function will search for an existing 
entry, such as [Windows Help], and write data below it. If a matching entry does not exist, a new one is written to 
WIN.INI. The data can be read from WIN.INI with GetProfileString() and GetProfileInt) for character and integer 
data, respectively, == : 

The problem with always using WIN.INI to store initialization data is that WIN.INI becomes very long. This slows 
down the Windows startup routines because all of WIN.INI is read every time Windows is started. There is also no. 
provision for deleting entries from WIN.INI when an application has been removed from the re WIN.INI files 
tend to collect large numbers of unnecessary entries over time. 

With Windows 3.0, support is provided for private initialization files. These files have the same format as WIN.IN I, 
but are specific to one application. The WritePrivateProfileString(), GetPrivateProfileString(), and GetPrivate- 
ProfileInt() functions are provided for simple support of these files. Private initialization files should be used for data 
that is specific to the application. WIN.INI should be used for data that might be used by more than one application, 
such as preferred color choices. 

Because WIN.INI holds initialization data common to all applications, an application that changes WIN.INI should 
notify all other running applications if a change is made. The application changing WIN.INI should send the 
WM_WININICHANGE to all applications (call PostMessage() with the hWnd parameter set to —1) after WriteProfile- 
String() is called. Do not do this for changes to private initialization files. 


MS-DOS and Disk File Function Summary : 
Table 20-1 summarizes the Windows disk file functions. The detailed function rarecne Hone are in the next section: 


DigDirList | Fills a list box control in a dialog box with a set of filenames. 


-DigDirListComboBox Fills a combo box control in a dialog box with a set of file names. 
DigDirSelect Retrieves the currently selected file name from a list box. 

" DigDirSelectComboBox Retrieves the currently selected file name from a combo box. 
GetDOSEnvironment Retrieves a pointer to the DOS environment string buffer. 
GetDriveType "Determines if a drive is fixed, removeable, or a network drive. 
GetEnvironment — __ Retrieves the Windows environment string for a device. 
GetPrvateProfieint __—_Retriaves an integer value from an application's private profile (.IN) file. 
GetPrivateProfileString Retrieves a character string from an application's private profile (.INI) file. 
" GetProfileint | Reads an integer value from the WIN.IN! file 

-GetProfileString Retrieves a character string from the WIN.IN! fie 
GetSystemDirectory ° ~—_Determines the path name of the Windows system directory. 
GetTempDrive Determines which drive to use for temporary files. 
GetTempFieName Creates a unique, temporary file name. 

GetWindowsDirectory Determines the path name of the Windows directory. 

close | ~ Closes a disk file. 

creat - Creates a new disk file, 

"_ liseek Moves to a new location in a disk file. 

open Opens a file for reading or writing data. 

_head | Reads data from a disk fie. | | te 
ite _. Whites data toa disk fle, © by aot gee 
OpenFie > ~*~ Creates, opens, or deletes fies. 
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Changes the environment variable settings for a port. 
Sets whether Windows shows the default critical error message. 
Changes the number of files an application can have open at once. 


WritePrivateProfileString 4 Copies a character string to an application's private profile (.INI) file." ; 


WriteProfileString 


‘Writes an entry to the WIN.INI file. 


Table 20-1. Disk File Function Summary. 


MS-DOS and Disk File Function Descriptions 
This section contains the detailed descriptions for the disk file functions. 


DicDmList 


lpPathSpec 
nIDListBox 


niDStaticPath_ 


mWin20 eWin30 mWindl 
Fills a list box control in a dialog box with a set of file names. 
int DigDirList(HWND hDig, LPSTR [pPathSpec, int nIDListBox, int nlDStaticPath, WORD 
wFileType); — 


List box controls are ideal for allowing the user to select a file name from a list. This function 
conveniently fills the list box with a set of file names which match a DOS file search RES 


Used in the File/Save, File/Load dialog boxes for most applications. 
int, nonzero if files were found. Zero if no files were found that matched lpPathSpec. 


: DigDirListComboBox(), DigDirSelect() 


HWND: The dialog box handle. 
LPSTR: A pointer to a character string containing the DOS file: ‘search string. For example, 
“CADOS\*.COM” would list all files in the DOS subdirectory with the .COM extension. — 


int: The dialog box ID value for the list box control. Normally the list box icon have the LBS_SORT 
style, so that the files are listed in ASCII sort order. . 


int: The dialog box ID value for a static text contro! that will be updated with the current path 
name, 


WORD: The DOS file attribute value. (See the list in Table 20-2.) Only files with the selected 
attributes will be displayed. 


EON EDGE RE EES 


Table 20-2 DOS File Attributes. 


Read/write data files with no other attributes set pomal files). 
Read only files. 
Hidden files. 
__ System files. 
S .bdirectories. 
Archived files. 


LB_DIR flag. Fig (iacke culeages acacia liad he A OS: 


message queue, rather than sending them directly. See the LB. ee 
_ Chapter 9, Windows Messages. 


Drives (A, B, C, ...). 


Exclusive bit. If this is set, only the specified le attribute type is recovered If not set, normal files. 
ee ee ee 


WINDOWS API BIBLE 


Related Messages LB_RESETCONTENT, LB_DIR 


Example This example, as shown in Figure 
20-2, creates a dialog box when the 
user clicks the “Do It!” menu item. 
The dialog box contains a list box, 
showing all of the files in the cur- 
rent directory. The dialog box also 
displays the directory name and the 
number of files displayed. When the 
user selects a file from the list box, 
the selection number and file name 

- are stored in global variables. This 
allows the calling WndProc() func- 
tion to display the current selection © Figure 20-2. DigDirList() Example. 
at the top of the window’s client 
area when WM_PAINT messages are processed. 

The dialog box is defined in a resource file created with the dialog box editor. 


EXAMPLEDIALOG DIALOG LOADONCALL MOVEABLE DISCARDABLE 20, 36, 162, 75. 
CAPTION “Example Dialog Box" 
FONT 10, "Helv" 
STYLE WS_BORDER | WS_CAPTION | WS_DLLGFRAME | DS _MODALFRAME ] WS_POPUP 
BEGIN 
CONTROL “OK", DLI_OK, "button", BS_DEFPUSHBUTTON | WS_TABSTOP | 
WS_CHILD, 102, 48, 40, 14 
CONTROL “", DLI_LISTBOX, "Listbox", LBS_STANDARD | LBS_HASSTRINGS | 
WS_BORDER | WS_VSCROLL | WS_CHILD, 5, 17, 87, 49 
CONTROL “Number of Files:", -1, “static”, SS_LEFT | WS_CHILD, 
102, 15, 54, 18 
CONTROL "", DLI_DIRSTRING, “static", SS_LEFT | WS_CHILD, 
10, 4, 141, 12 
CONTROL "", DLI_NUMFILES, “static”, SS_LEFT ]| WS_CHILD, 
102, 37, 41, 10 ; 
END : ~ 


The dialog box control ID numbers are defined in a separate header file, GENERIC.HD. 


Hdefine DLI_LISTBOX 104 

#define DLI_LNUMFILES >» ' 103 2. 
H#define DLI_DIRSTRING - fs 4020 

Hdefine DLI_OK 101 


The following listing shows the dialog box function at the end. The function must be listed in 
the EXPORTS section of the application’s .DEF definition file, and it must have a function proto- 


' type in the header file. 
int nSelection = 0; /* global variables */ 
char cSelection C128] ; 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
C ; : 


FARPROC  UpfndlgProc ; 

PAINTSTRUCT Hee ee 

char cBuf £128] ; 

switch CiMessage) /* process windows messages */ 
{ 


' case WM_PAINT: 
BeginPaint ChWnd, &ps) ; 
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TextOut (ps.hdc, 10, 10, cBuf, wsprintf (cBuf, 
“The current selection is number 4d, %s", 
nSelection, (LPSTR) cSelection)) ; 

EndPaint (hWnd, &ps) ; os 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* run dialog box */ 


LpfnDlgProc = MakeProcInstance (DialogProc, 
ghinstance) ; 

DialogBox CghInstance, “ExampleDialog", hWnd, 
: LpfnDlgProc) ; 

FreeProcInstance (ltpfnDlgProc) ; 

InvalidateRect (hWnd, NULL, TRUE) ; 

break ; 

case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; 
case WM_DESTROY: ¢ /* stop application */ 
é PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
} 
return (OL); 


BOOL FAR PASCAL DialogProc (HWND hDlg, WORD wMess, WORD wParam, LONG LParam) 
{ 


int nFiles ; 


switch (wMess) 


t 
sase WM_INITDIALOG: : 
DigDirList (hDlg, "*.- , DLI_LISTBOX, 
DLI_DIRSTRING, 0) ; 
nFiles = SendDlgitemMessage ChDlg, DLI_LISTBOX, ron 
LB_GETCOUNT, Q, OL) ; are 
SetDlgItemInt (hDlg, DLI_NUMFILES, nFiles, TRUE) ; 
return TRUE ; : . 
case WM_COMMAND: wo /* One of the controls was activated */ 
switch (wParam) 
{ 
case OLI_OK: 
EndDialog (hDlg, 0) ; 
return TRUE ; 
case DLI_LISTBOX: 
if CHIWORD (lParam) == LBN_SELCHANGSE) 
{ e 
nSelection = SendDlgItemMessage (hDlg, 
DLI_LISTBOX, LB_GETCURSEL, 0, OL) ; 
DlgDirSelect ChDdlg, 
(LPSTR) cSelection, 
DLI_LISTBOX) ; 
} tr 
} 
return TRUE ;- 
case WM_DESTROY: 
EndDialog ChDlg, 0) ; 
return TRUE ; 
} 


return FALSE ; 
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DicDrListComsoBox | . aWin20 @Win30  @Win3.l | 


Purpose Fills a combo box control in a dialog box with a set of file names. 
Syntax int DigDirListComboBox(HWND hDig, LPSTR [pPathSpec, int ete! int nlDStaticPath, 
WORD wFileType); 
Description Combo box controls are ideal for allowing the user to select a file name from a list. This function 
fills the combo box with a set of file names which match a DOS file search string. 
Uses Used in the File/Save, File/Load dialog boxes. . 
Returns int, nonzero if files were found. Zero if no files were found matching [pPathSpec. 
See Also DigDirList(), DigDirSelectComboBox() 
Parameters . 
hADig HWND: The dialog box handle. 
lpPathSpec LPSTR: A pointer to a character string containing the DOS file search string. For example 
“CADOS\*.COM” would list all files in the DOS subdirectory with the .COM extension. 
* IDListBox int: The dialog box ID value for the combo box control. Normally the combo box will have the 
, CBS_SORT style, so that the files are listed in ASCII sort order. 
nlDStaticPath int: The dialog box ID value for a static text contro! that will be updated with the current path 
name. 
wFileType WORD: The DOS file attribute value. (See the ist in Table 20-3. ) Only files with the selected 


attributes mi be displayed. 


oR eh 
Moctings 7; eee Be Saat 


0x4000 
~ 0x8000 


Table 20-3. DOS File Attributes 


Related Messages CB_RESETCONTENT, CB_DIR 


‘Example | 


- Showing the selected file in the edit 


Read/urite data files with no other attributes a (normal files). 

Read only files. 

Hidden files. 

System files. 

Subdirectories. 

Archived files. 
LB_DIR flag. This places messages associated with fi illing the combo box on the application's 


message queue, rather than sending them directly. See the LB_DIR message sl ad in 
Chapter 9, Windows Messages. 


Drives (A, B, C.,...). 


Exclusive bit. If this is set, only the specified file attribute type is recovered. If not set, normal files 
are displayed in addition to the types listed. 


This example, as shown in Figure 20- Tt Number of 
8, is identical to the previous ex- —— pq (Files: 
ample, except that a combo box is a a 97 

used in place of the list box for show- : 
ing the list of files. The combo box 
has the advantage of automatically Bgenenet 


control at the top ofthe combo box. Figure 20-3. DigDirListComboBon{ y) Example. 
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The SDK Dialog Box Editor is used to create the dialog box definition file. This can either be 
physically added to the program’s .RC resource file or included via an #include statement. 


EXAMPLEDIALOG DIALOG LOADONCALL MOVEABLE DISCARDABLE 20, 36, 162, 75 
CAPTION “Example Dialog Box” 
FONT 10, “Helv” ; 
STYLE WS ~BORDER |] WS_CAPTION | WS_DLGFRAME | DS_MODALFRAME | WS_| POPUP 
BEGIN 
CONTROL “OK", DLI_OK, “button”, BS_DEFPUSHBUTTON | WS_TABSTOP 
[| WS_CHILD, 102, 48, 40, 14 
CONTROL “Number of Files:", -1, “static”, SS_LEFT | WS_CHILD, 
. 102, 15, 54, 18 
CONTROL “", DLI_DIRSTRING, “static”, SS_LEFT | WS_CHILD, 
10, 4, 141, 12 
CONTROL "", OLI_LNUMFILES, “static”, SS_LEFT | WS_CHILD, 
102, 37, 41, 10 
CONTROL “", DLI_COMBO, “combobox", CBS_SIMPLE } CBS_SORT | 
WS_VSCROLL | WS_CHILD, 7, 17, 89, 57 


END 
The dialog box control ID numbers are defined in a separate header file, GENERIC.HD. 
Hdetine DLI_COMBO 104 
Adefine DLI_NUMFILES, 103 
Hdefine DLI_DIRSTRING ‘102 
define DLI_OK 101 


Only the dialog box procedure is shown in the following example. The WndProc() function is 
identical to the example shown above under the DigDirList() function description. The dialog 
box function must be listed in the EXPORTS section of the application’s .DEF definition reas and _ 
should have a function prototype in the program’s header file. 


res FAR PASCAL DialogProc CHWND hDlg, WORD wMess, WORD wParam, LONG LParam) 


int nFiles ; 


switch (whess) 
€ 


case WA_INITDIALOG: 
DlqDirListComboBox (hDig, "*.*", DLI_COMBO, 
DLI_DIRSTRING, O) ; 
nFiles = SendDlgIitemMessage (hDlg, DLI_COMBO, 
CB_GETCOUNT, Q, OL)'; 
SetDlgitemInt ChDtg, DLI _NUMFILES, nFiles, TRUE) ; 
return TRUE ; 
case WMH COMMAND: . /* One of the controls was activated */ 
switch (wParam) 
L é 


: case DLI_OK: 
EndDialog Chdlg, 0) ; 
_ return TRUE ; 
case DLI_COMBO: 
if CHIWORD (lParam) == LBN_SELCHANGE) 


£ 
nSelection = SendDlgItemMessage (hDlg, 
DLI_COMBO, CB_GETCURSEL, Q, OL) ; 
DigDirSelectComboBox ChDtg, 
(LPSTR) cSelection, 
e DLI_COMBO) ; 


return TRUE ; 
case WM_DESTROY: ae 
. EndDialog (hDlg, 0) ; 
- return TRUE ; 
} i —— ; ; oe 
return FALSE ; 2 4 i Oe 
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-DieDirSeELecr . . @Win20 woWin3.0 mWin3.1 
Purpose _ Retrieves the currently selected file name from a list box. 
Syntax BOOL DigDirSelect(HWND hDig, LPSTR lpString,.int nIDListBox); : 
Description This function assumes that the list box in a dialog box was filled with file names using the 


DigDirList() function. The currently selected file or directory name is copied to the memory 
buffer pointed to by /pString. This function is equivalent to sending the LB_GETCURSEL and 
LB_GETTEXT messages to the list box control. 


Uses Used in File/Save and File/Load dialog boxes. 

Returns BOOL. Nonzero if the item selected is 4 directory name, otherwise zero. 

See Also DigDirList() 

Parameters. 

hDig HWND: The dialog box handle. 

lpString LPSTR: A. pointer to a memory buffer that will hold the name of the file or directory selected. 


Directories will be displayed with square brackets surrounding the aes name. The brackets _ 
are not copied to the memory buffer. 


nIDListBox int: The ID value for the list box control in the dialog box. 
" Related Messages LB_GETCURSEL, LB_GETTEXT 
Example See the example under the DigDirList() function description. 
DicDirSeELecTtComsBoBox | OWin2.0 mWin3.0 sWin3.1: 
Purpose Retrieves the currently selected file name from a combo box. 
Syntax BOOL DigDirSelectComboBox(HWND hDig, LPSTR lpString, int nIDComboBoz); 
Description This function assumes that the combo box in a dialog box was filled with file names using the 


DigDirListComboBox() function. The currently selected file or directory name is copied to the 
memory buffer pointed to by /pString. This function is equivalent to sending the CB_GETCURSEL 
and CB_GETLBTEXT messages to the combo box control. 


Uses Used in File/Save and File/Load dialog boxes. 


Returns BOOL. Nonzero if the item selected is a directory name, otherwise zero. 

See Also DigDirListComboBox() 

Parameters 

hDig HWND: The dialog box handle. 

lpString LPSTR: A pointer to a memory buffer that will hold the name of the file or directory selected. 


Directories will be displayed with square brackets surrounding the ei Le name. The brackets 
are not copied to the memory buffer. 


nIDComboBox int: The ID value for the combo box control in the dialog box. 
Related Messages’ CB_GETCURSEL, CB_GETLBTEXT 


Example See th example under the DlgDirListComboBox(Q) function description. 
GETDOSENVIRONMENT __ | | | mWin20 mWin30  mWin3.l 
Purpose Retrieves a pointer to the DOS environment string buffer. 

Syntax LPSTR GetDOSEnvironment(void); 


Description When you issue a PATH or SET command from within MS-DOS, the string is stored in the DOS 
environment buffer. This memory area is expanded by DOS to. hold all of the input strings. 


Uses 
Returns 
See Also 

- Parameters 
Example 
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GetDOSEnvironment() retrieves 2 pues 
pointer to this memory area. Each (Esme bald 

string is separated byasingleNULL {-Dolt! Quit 

character. The end of the last envi: fCOMSPEC=C:\DOS\COMMAND.COM 

ronment string is marked by two [SOUND = CSB 

NULL characters. The environment PROMPT=SPSG 

string is not updated after the appli. JPATH ONLIBsCs MINDEVIIB AC\BINB; 


cation or DLL is loaded. Changes af- 
ter that point are not reflected in Figure 20-4. GetDOSEnvironment() Example. 


the returned memory area. This 
function will work within a DLL (dynamic link library). 


Frequently used to find which directories are on the current PATH. 
LPSTR, a pointer to the MS-DOS environment string memory buffer. 
GetEnvironment(), GetWindowsDirectory() 

None (void) ; 


This example displays the current DOS environment variables on the window's client area, as 
shown in Figure 20-4. Note that the output code must skip over the single NULL characters that 
separate the environment strings, and must stop when it finds two NULL characters in a row. 


Long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


PAINTSTRUCT ps ; 

LPSTR Lpstr ; 

int nLine ; ; 
switch (iMessage) /* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
Lpstr = GetDOSEnvironment () ; 
TextOut (ps. hdc, 0, 0, Lpstr, Lstrlen Clpstr)) ; 
nLine =1; 
. do ¢ 
if (*lpstr == 0 && *(lpstr +1) '= 0) 
t . 4 


lpstr++ ; 
TextOut (ps.hdc, 0, nLinet+ * 15, Lpstr, 
istrlen (tipstr)) ; 


} 

while (*lpstr++ + *tpstr) 7 /* not two nulls */ 

EndPaint (hwnd, &ps) ; 

break ; 
[Other program lines] 
GeTDriveTyre : gWin20 eWin30 wWin3.1 
Purpose Determines if a drive is fixed, removeable, or a network drive. SG ; 
Syntax WORD GetDriveType e(int nDrive); 
Description Network and removeable disks are much slower than fixed Dee as ella see 

: disks, It is frequently desirable to know which disk is the fast- fprive C: Fixed 
est available for writing temporary files, etc. sDrive D: Does not exist. } 

Returns WORD, zero if unknown, 1 if the specified drive does not exist: Figure 20-5. GetDriveType() 


Otherwise, one of the values in Table 20-4 is returned. Example. 
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DRIVE_REMOVABLE Floppy disk. 


~ DRIVE_FIXED - Hard disk. 
_ DRIVE_REMOTE Network drive. 
Table 20-4. GetDriveType() Returned Values. 
- SeeAlso GetTempDrive() | 
nDrive _ int:, The drive to check. 0 for the A drive, 1 for the B drive, etc. 
Example This example displays the drive type of the first four drives when the user clicks the “Do It!” menu 
. item. . . 
long FAR PASCAL WndProc CHWND hind, “eiGned ideakece: WORD wParam, LONG (lParam) 
{ ; 
HOC. | : hoc ; 
int i, nType ; 
char c, cBuf [128] ; 
suitch. (iMessage) ’ . je process wihdows messages */ 
{ — 
case WH_COMMAND: ' /* process menu items */ 
switch (wParam) 
{ . 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hoc = GetDC (hWnd) ; ce 
for (4¢=O;1< 5) ¢ i++) 
co 
nType = GetDriveType C1) ;> 
switch (nType) 
t 
‘case DRIVE_REMOVABLE: 
TextOut (hoc, 0, 15 * i, cBuf, 
: ‘wsprintf (cBuf, 
“Drive Xe: 48", ‘A’ + i, 
(LPSTR) “Removeable")) ; 
break ; 
case DRIVE_FIXED: 
TextOut (hoc, 0, 15 * 1, cBuf, 
usprintf (cBuf, 
“Orive Xe: Xa", °A' #1, 
CLPSIR) “Fixed")) > 
: break ; 
, case DRIVE_REMOTE: 
% | TextOut ChdC,'0, 15 * 4, cBuf, 
-  wsprintf (cBuf, . . 
“Drive 4c: 28s", ‘A' +4, 
_ CLPSTR) “Removeable")) ; 
break ; 
default: 
; TextOut ChDdC, 0, 15 * i, cBut, 
wsprintft (cBuf, 
“Drive Xc: %3", "A' + 4, 
CLPSTR) “Does not exist.")) “3 
break ; 
} 
- 
; Releasedc Chifnd, hoe) ; 
oa break ; : 
{Other program lines] — 
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GrtENvIRONMENT eWin2.0 mWin30 mWin3l 

Purpose Retrieves the Windows environment string or a device. 

Syntax int GetEnvironment(LPSTR lpPortName, LPSTR lpEnviron, WORD nMaxCount); 

Description The Windows GDI (Graphics Device Interface) maintains a string table for each port. If the port 
has been initialized via the Windows setup program, the port environment string will be set. 
Otherwise, the environment string will not exist, and Get- : 
Environment() will return zero. GetEnvironment() willreturn Jalal [~. [a 
the length of the environment string if lpEnviron is set to J Do lt! Quit 
NULL. 7 {| Doltt Quit | 

Uses A quick way to get the printer name. The lpPortName variable PC LiH P Las erJ et 
will normally be “LPT” for the printer device. Figure 20-6. GetEnviron- 

Returns int, the number of characters copied to lpEnviron. ment() Example. 

See Also GetDOSEnvironment(), SetEnvironment() 

Parameters 

lpPoriName LPSTR: A pointer to.a null-terminated character string containing the port name. For example 
“LPTI. ” 

lpEnviron LPSTR: A pointer toa character buffer that will hold the environment string. If this value is set to 
NULL, GetEnvironment() will return the length of the environment string. 

nMaxCount int: The maximum number of characters to copy to lpEnviron. — 

Example This example, as shown in Figure 20-6, ae the GDI environment string associated with the 


LPT! port. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


PAINTSTRUCT 
char 


switch (iMessage) 


{ 


ps ; 
cBuf £128] ; 
/* process windows messages */ 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
GetEnvironment ("“Lpti", cBuf, 128) ; 
TextOut (ps.hdc, 0, 0, cBuf, ‘strlen (cBuf)) ; 
ehdPaent ChWnd, ps) ; 


break ; 
[Other program lines] 
GETPRIVATEPROFILEINT mWin2.0 mWin30. mWin31 
Purpose Retrieves an integer value from an application’s private profile (.INI) file. 
Syntax WORD GetPrivateProfileInt(LPSTR ipApplicationName, LPSTR [pKeyName, int al ate 
LPSTR lpFileName); 
Description The best way for a program to “remember” user preferences, such as favored colors and sub- 


directory names, is to write them to an initialization file. For items that may affect move than one 
application, this should be the main WIN.INI file. For items that will affect only the application 
itself, this should be a private .INI file. GetPrivateProfileInt() reads an integer value. The value is 
assumed to be in a file with the format 


Capplication name] 
keyname = int value 
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Uses. 
Returns 


~ See Also | 
Parameters 


_ These files are best created and maintained using the WritePrivateProfileString() function. 


Reading in saved values, such as the window size and location when last closed. 


‘WORD, the'value read. If the key name exists, but the value following the equal sign is not a 
- positive integer, the function returns zero. If the key name does not exist, the nDefault value is - 


returned. 
WitePrivateProestrng) GotPrivateProfieString() 


cies eet LPSTR: A inte toa character string that contains the application name in the private .INI file. 


tpkeyName 


nDefault 
lpFileName 


Example 


-IpFileName. : 


. This is the string that appears inside the square brackets. 


LPSTR: A pointer to the key name in the private .INI file. This is the string to the left of the equal 
int: The default value to return if the lpKeyName match is not found. 


LPSTR: A pointer to a character string containing the private .INI file name. The file is assumed 
to be in the Windows subdirectory unless a path name is included with the file name in 


a | ee, generic” oe fe fa 


When started, this example creates a private profile file, 


- GENERIC.INI; in the Windows subdirectory. The file is _ 
written with two values under the heading [TestApp].. & 


The first value is an integer with the key name “Value,” Figure 20-7. GetPrivateProfileint() 


which is set to 487. The second value is a string with the _ Exanvple. 


key name “StringConst,” which is set to “This String.” 


When the user clicks the “Do It!” menu item, the private profile string is read, and the two values 


are extracted. They-are written to the window’s client area as shown in Figure 20-7. 


© GENERIC.INI File Created 


CTestApp] 
Value=437 - 


StringConst=This strinat 


© GENERIC.C WndProc() Function i 3 
long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


HOC hdc ; 

char cBuf £128], szStringVal C32] ; 

int nValue ; 

switch CiMessage) ' /* process windows messages */ 
{ 


case WM CREATE: ; 
Mette Rts veRchrorl Leste ing C'Testapp", "Value", "437", 
“GENERIC.INI") ; : 
WritePrivateProfileString C"TestApp", “StringConst", 
“This string!", "GENERIC.INI") ; 


break ; 
case WM_ COMMAND: , _ /* process menu items */ 
switch. (wParam) 
reo { ; ‘ * 
': Case IDM_DOIT:. . . :..:. /*® User hit the "Do it" menu item 7 


hDC = GetDC ChWnd) ; 
_ aVvalue = GetPrivaterrofileint ("TestApp", "Value", 
-1, "GENERIC.INI") ; 
GetPrivateProfileString C'Testapp", der ingeoases, 
“<€none>", szStringVal, 32, "GENERIC.INI") ; 
TextOut (hDC, 0,.0, cBuf, wsprintf (cBuf, 
“Value = 4d, String = %s", nValue, 
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Ere) szStringVal)) ; 
~ ReleaseDC ChWnd, hoc) ; 


i ay break ; 

[Other program lines]: 

GETPRIVATEPROFILESTRING 7 | mWin20 mWin3.0 mWin31 

Purpose — Retrieves a character string from an application’s private profile (.INI) file. 

Syntax int GetPrivateProfileString(LPSTR lpApplicationName, LPSTR lpKeyName, LPSTR lpDefault, 
LPSTR lpReturnedString, int nSize, LPSTR lpFileName); 


Description The best way for a program to “remember” user preferences, such as subdirectory names, is to 


write them to an initialization file. For items that may affect more than one application, this. - 


should be the main WIN.INI file. For items that will only affect the application itself, this should 
be a private .INI file. GetPrivateProfileInt() reads a character string. The string is assumed to be 
in a file with the format 


Capplication name] 
keyname = string 


These files are best created and maintained using the WritePrivateProfileString() function. 
Uses Reading saved values, such as the last file(s) read, or the working subdirectory path name. 


Returns int, the number of characters copied to the lpReturnedString buffer. If the returned string is 
| truncated to fit the nSize parameter, only the number of copied characters is returned. 

See Also GetPrivateProfileInt(), WritePrivateProfilestring() 

Parameters 


perniicanonName LPSTR: A pointer to a character string that contains the ee name in the private .INI file. 
This is the String that appears inside the square brackets. 


IpKeyName — LPSTR: A pointer to the key name in the private .INI file. This is the string to the left of the equal 

sign. If lpKeyName is set to NULL, all of the key names are copied to the buffer pointed to by 
lpReturnedString. 
lpDefault LPSTR: The default string to return if the jpKeyName match is not found. 
lpReturnedString LPSTR: A pointer to a character buffer to hold the returned string. The buffer must be at least 
, *e nSize bytes long. 

nSize. ~—_ int: The maximum number of characters to copy to IpRoturnedString.. 

lpFileName ~. .LPSTR: A pointer to a character string containing the private .INI file name. The file is auton 

. a * to be in the Windows subdirectory unless a path name is included with the file name in 

lpFileName. 

Example See the previous example under the GetPrivateProfileInt() function description. 

GetTPRoFILEINT | | mWin2.0 mWin30 mWin3.1 

Purpose — Reads an integer value from the WIN.INI file. 

Syntax WORD GetProfileInt(LPSTR lpApplicationName, LPSTR lpKeyName, int nDefalt); 


Description © Windows uses the WIN.INI file to initialize applications. With Windows 3.0, support is provided 
. for both private initialization files and the general file WIN.INI. WIN.INI should be used for pro- 
grams that have settings that impact more than one application. Private profile files should be 
used for initialization data that only impacts one application. GetProfileInt() reads an integer 
value from WIN.INI. The value is assumed to be in a file with the format 


Capplication name] 
keyname = int value 
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Uses The integer value can either be as- 
sociated with a specific program, or 
one of the parameters Windows 
reads on startup (for example Cur- 

- sorBlinkRate=460). Integer = 358, String = Test string 

Returns WORD, the value read. If the key Baume DST SAS RET ET 

A name exists, but the value following Figure 20-8. GetProfileIni() Example. 
the equal sign is not a positive inte- 
ger, the function returns zero. If the key name does not exist, the nDefault value is returned. 


See Also : : WriteProfilestring(), GetProfileString(), Golindonalirecsati() 
~ Parameters 


lpApplicationName LPSTR: A pointer to a character string that contains the aapiltation name in the WIN.INI file. 
This is the string that appears inside the square brackets. 


lpKeyName LPSTR: A pointer to the key name in the private .INI file. This is the string to the left of the equal 
. sign. 

nDefault: .~... int: The default-value to return if the /pKeyName match is not found. 

Example ... — This example, illustrated in Figure 20-8, writes an integer and a string constant to the WIN.INI 


file on startup. When the user clicks the “Do It!” menu item, the values are retrieved from WIN. INI 
and displayed on the window’s client area. 


© The Bottom of the WIN.INI File after Running GENERIC.C 
CGeneric] 

IntValue=358 

StringConst=Test string 


“© GENERIC.C WndProc() Function 


‘Long: FAR PASCAL WndProc (CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HOC hoe ; 

char end £128], szStringVal [32] ; 

int 7 a nvalue : 

auttch Cittessage), /* process windows messages */ 
{ : . 


case WM_CREATE:. a : 
WriteProfileString "Generic", “IntValue", "358") ; 
WriteProfileString ("Generic", "StringConst", © 
"Test string”) ; 
break ; ; 
case WM_ COMMAND: /* process menu items */ 
- switch (wParam). 


case IOM_DOIT: /* eae hit the "Do it" menu item */ 
; -. * RDC = GetDC ChWnd) ; 
nValue = GetProfileint ("Generic", "IntValue", -1) 
GetProfilestring ("Generic", "StringConst", 
oo “<none>", szStringVal, 32) ; 
4 TextOut ChDC, 0, 0, cBuf, wsprintf (cBuf, 
i “Integer = 4d, String =%s", nVelue, 


. 
cd 


a ; Surin? szStringVal)) ; 
ReleaseDC snuads: hdc) ; 
break ; 


[Other program lines] 
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GETPROFILESTRING _  mWin20 mWin3.0 mWin3l 

Purpose Retrieves a character string from the WIN.INI file. 

Syntax _ ’ int GetProfileString(LPSTR DELP HR IENGNE, LPSTR lpKeyName, LPSTR ia LPSTR 

ee lpReturnedString, int nSize); 

Description Windows uses the WIN.INI file to initialize applications. With Windows 3. 0, support i is srovided 
for both private initialization files and the general file WIN.INI. WIN.INI should be used for pro- 
grams that have settings that impact more than one application. Private profile files should be 
used for initialization data that only impacts one application. GetProfileString() reads a charac- 
ter string from WIN.INI. The value is assumed to be in a file with the format 
Capplication name] 
keyname = string : 

Uses Useful both for reading strings associated with an application and strings that Windows reads on 
startup (for example, device=PCL / HP LaserJet,HPPCL,LPT1:). 

Returns int, the number of characters copied to the [pReturnedString buffer. If the returned string is 
truncated to fit the ~Size parameter, only the number of copied characters is returned. 

See Also GetProfileInt(), WriteProfileString(), GetWindowsDirectory() 

Parameters 


lpApplicationName LPSTR: A pointer to a character string that contains the application name in n the WIN.INI file. 


This is the string that appears inside the square brackets. 


lpKeyName LPSTR: A pointer to the key name in the WIN.INI file. This is the string to the left of the equal 
sign. If IpKeyName is set to NULL, all of the key names are copied to the buffer aia to by 
lpReturnedString. 

lpDefault LPSTR: The default string to return if the IpKeyName match is not found. 

lpReturnedString LPSTR: A pointer to a character buffer to hold the returned string. The buffer must be at least 
nSize bytes long. 

nSize int: The maximum number of characters to copy to lpReturnedString. 

Example See the previous example under the GetProfileInt() function description. 

GETSYSTEMDIRECTORY | wg Win2.0) «6 Win3.0 = Win3.l 

| Purpose Determines the path name of the Windows system directory. 

Syntax WORD GetSystemDirectory(LPSTR [pBuffer, WORD nSize); 

Description The system directory contains the Windows driver files and the dynamic link libraries that Win- 
dows uses to load the GDI and Kernel functions. Depending on how Windows was installed, this 
directory can be on different drives and can have different names. The full path name of the 
system directory is copied to the buffer pointed to by pBuffer. The path name will not include the 
terminating backslash (\) character unless the system directory is the root directory. 

Uses Programs that install drivers should add them to the system subdirectory. | 

Returns WORD, the number of characters written to the buffer pointed to by lpBuffer. 

See Also GetWindowsDirectory() 

Parameters 

lpBuffer LPSTR: A pointer to a character buffer that holds the Je detory name. This buffer must be at least 


nSize bytes long. 
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nSize . ~ int: The maximum number of characters te copy to 


the buffer pointed to by pBuffer. 7 generic | Ma 
; | 
’ Example The system directory is written to the window's cli- . Do It Q uit 


ent area when the user clicks the “Do It!” menu item, - 
as shown) in Figure 20- 9. 


C: {WINDOWSISYSTEM | 


_ Figure 20-9. GetSystemDirectory( ) 
_ Example... 


Long FAR PASCAL WndProc CHWND Roads unsigned iMessage, WORD eg LONG LParam) 
{ ; 


HDC hoc; 
char eae C128] ; 
switch CiMessage) . /* process windows MESS Age? */ 
| case WM_COMMAND: . |* process menu items */ 
switch (wParam) 
{ Me 
case IDM_ DOIT: /* User hit the "Do it" menu item */— 
hOC = GetDC (hWnd) ; 
. GetSystemDirectory (cBuf, 128) ; 
TextOut (hdc, 0, 0, cBuf, lstrlen (cBuf)) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
[Other prograe lines] 
| GerTempDrive | mWin2.0 mWin30 mWin3l 
Purpose Determines which drive to use for ‘einpOnly files. 
Syntax BYTE GetTempDrive(BYTE cDriveLetter);. CE ee eee 
. are ; Bs, aah . : generic °° [= f= 
Description This function. is used with GetTempFileName() to 
create temporary files. The drive letter returned is emp File = C:)GENOO01.TMP 
the first hard disk drive letter, if the system has one. . ON 
Read string = This is the data. 
Uses Temporary files can be used to store memory data if. 
_ the system becomes low on memory. a Figure 20-10. GetTempDrive( y 
_ Returns _ BYTE, the drive letter as an ASCII character. Exrample. 
See Also GetTempFiteName() 
Parameters es a . 
cDriveLetter . BYTE: Ifzero, the function will return the drive letter for the disk drive that Windows is running 
on (usually the fastest drive). If an ASCII letter, the function will return the next hard disk drive 
letter, starting with the cDriveLetter drive. 
Example | This example, which is illustrated in Figure 20-10, ‘ieatés a temporary file anil writes a character 


string to it. When the user clicks the “Do It!” menu item, the file is read and its contents are 
displayed on the window’s client area. 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG. lParam) 
cd : ; 


HDC hDC ; SY ke 
static char szTempFile C144], cData CJ] = {"This is the data."} ; 
char cBuf £1283, cReadBuf [64] ; 

BYTE Oo r: cDriveLetter ; 

HANDLE hFileHandle ; 

int nStatus, nFileLong ; 

switch (iMessage) /* process windows messages */ 
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case WM_CREATE: 
cDriveLetter = GetTempDrive (0) >; © 
GetTempFileName (cDriveLetter | oe FORCEDRIVE, 
“GEN", 1, szTempFile) ; 
hFileHandle = _\creat (szTempFile, 0); 
nStatus = _lwrite ChFileHandle, cData, \strlen (cData)) ; 
if (nStatus != -1 && hFileHandle != -1) 
_tclose (hFileHandle) ; 


else : 
MessageBox (hWnd, "Could not open temp file.", 
“File Error", MB_OK) ; 
break ; ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ \ ; 
case IDM_DOIT: . /* User hit the "Do it" menu item */ 
hDC = GetDC: (hWnd) ; 
hFileHandle = _lopen (szTempFile, OF_| READ) ; 
if. (hFileHandle '= -1) 
{ “ft find file Length */ 
nFileLong = (int) _llseek ChFileHandle, OL, 2) ; 
, “7* return to beginning #1 
_llseek (hFileHandle, OL, 0) ; 
/* read the data into cReadBuf */ 
_lread (hFileHandle, (LPSTR) cReadBuf, 
nFileLong) ; 
_lclose (hFileHandle) : 
} 
TextOut (hDC, 0, 0, cBuf, wsprintf (cBuf, 
“Temp File = %s", (LPSTR) szTempFile)) ; 
TextOut ChDC, 0, 20, cBuf, wsprintf (cBuf, 
“Read string. = %s", CLPSTR) cReadBuf)) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_ QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: : /* stop application */ 
Postaul tNessage (O) ; 
break ; 
default: /* default windows message processtog */ 


retuin DefWindowProc: (hWnd, iMessage, wParam, lParam) ; 


} 
return (COL) ; 


} f 

GetTTemPpFILENAME | mWin2.0 mWin3.0 mWin31 

Purpose _ Creates a unique, temporary file name. . 

Syntax int GetTempFileName(BYTE cDriveLetter, LPSTR ipPrefieString, WORD wUnique, LPSTR 
lpTempFileName); 

Description This function generates a unique temporary file name that the application can use to store data. 
The file name will include the full path name in the form 
drive:\pathYfilename.tmp . 

The path will either be the root directory (eg. ,C:\) or the path name specified by the TEMP 

environment variable. Environment variables are created from DOS using the SET command (eg., 
SET TEMP=C;\TEMP). 

Uses Temporary files can be used to store memory data if the system becomes low on memory. 
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A 

Returns int, a unique numeric value used in the temporary file name. If wUnique was set toa nonzero 
value, that value will be returned. 

See Also GetTempDrive() 

Parameters 

- eDriveLetter BYTE: The drive letter as an ASCII character. If zero, the default drive is used. Use GetTemp- 
‘Drive() to determine the best drive to use. 
Windows will ignore the cDriveLetter drive specification unless there is no hai disk. To 
force the selection of drive cDriveLetter, OR the drive letter with TF_FORCEDRIVE using the C 
| _ language binary OR operator (1), This sets the high-order bit to one. 

lpPrefixString LPSTR: A pointer to a character string with which to start the temporary file. The characters 
must be from the OEM character set. Use AnsiToOem() to convert the string if the prefix is based 
on the default Windows character set (ANSI). Normally, only two or three characters are sup- 
plied to leave room for the unique file name numbers.’ . 

wUnique- WORD: Specifies an unsigned integer. If nonzero, the function will use wU/nique to create a file 

. name. IfwUnique is zero, GetTempFileName() forms a unique file name from the system time. If 
a file with that name exists, the value is incremented until a unique file name is found. The file is 
then created and closed. This is the only case where GetTempFileName() creates a file. 
lpTempFileName LPSTR: A pointer to a memory buffer to hold the temporary file name. The buffer should be at 
least 144 bytes long. The characters written to the buffer will use the OEM character set. 

Example . See the previous example under the GetTempDrive() function description. 

GETWINDOwSDIRECTORY Win2.0 eWin30 mWin3.l 

Purpose Determines the path name of the Windows directory. 

Syntax WORD GetWindowsDirectory(LPSTR [pBuffer WORD nSize); 

Description The Windows subdirectory contains WIN.COM and WIN.INI. Depending on how Windows was 
installed; this directory can be on different drives and have different names. The full path name 
of the Windows directory is copied to the buffer pointed to by pBuffer. The path name will not 
include the terminating backslash (\) character unless the system directory is the root directory. 

Uses The Windows subdirectory is frequently where applications install dynamic link library files 
(DLLs). Le a never ee 

Returns» WORD, the number of characters written to the buffer 3 gene ¥ 
pointed to by lpBuffer. i Dolt! Quit 

See Also GetSystemDirectory() ICAWINDOWS aoe 

Parameters EE | 

IpBuffer LPSTR: A pointer toa character buffer to holdthedirec- /*gwre 20-11. GetWindows- 

' tory name. This buffer must be at least nSize bytes long. Directory() sae ea 
nSize int: The maximum number of characters to copy to the buffer poinied to by lpBuff: 
Example | The Windows subdirectory i is displayed in the client area a when the user Hus the “Do It!” menu 


item, as shown in Figure 20-11. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


C - 
HDC hDC ; 
char cBuf £128] ; 
switch (iMessage) /* process windows messages */ 
{ be * 


case WM_COMMAND: . /* process menu items */ 
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—w 


switch (wParam) 


case IDM_DOIT: — /* User hit the "Do it" menu item */ 
hDC = GetDC (hWnd) ; 
GetWindowsDirectory (cBuf, 128) ; 
TextOut (hDC, 0, 0, cBuf, tstrlen (cBuf)) ; 


; Rebeasen’ (hwnd, hdc) >; 
: ; break ; 

[Other program lines] 

_LCLOSE @Win2.0 wWind0 mWind! 

Purpose Closes a disk file. 

Syntax int _Iclose(int hFile); 

Description This function closes a disk file opened with either _Icreat(), lopen(), or OpenFile(). As soon as 
it is closed, the file handle becomes invalid. The file cannot be read from or written to until it is 
reopened. 

Uses Files should be closed as soon as possible after they are created or opened. Doing so avoids having 

; the application terminate without closing the file. 

Returns int, zero if the file was closed, —1 on error. 

See Also _lopen(), _Icreat(), OpenFileQ 

Parameters . ‘oe be F te Pa ee ae a Be ; “ae ; 2 ; = ae 

hFile int: The file handle. This is an inte- |) AAMAREMNRNUUNENEE hs Sana I~ [*.. 
ger value that DOS returns when a Do ft! Quit 
file is opened or created. The value [Read string = String data for the file. 
is obtained by calling either 
_lopen(), _Icreat(), or OpenFile(). Figure 20-12. _Iclose() Example. 

Example When the WM_CREATE message is processed, the file MYFILE.TXT is created on the default 


drive and directory. A character string is written to the file. When the user clicks the “Do It!” 
menu item, the file is read. The file contents are written to the window’s client area, as shown in 
Figure 20-12. 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC hoc ; : 

static char cData CJ] = {"String data for the file."} ; 

char cBuf [128], cReadBuf £64] ; 

int hFileHandle ; : 

int nFilelong ; 

switch (iMessage) : /* process windows messages */ 


{ 


case WM_CREATE: 
hFileHandle = _tcreat ("MYFILE. TXT", 0) ; 
if (hFileHandle != -1) 


£ ; 
_lwrite (hFileHandle, cData, Istrlen (cData) + 1) ; 
_lclose (hFileHandle) ; 
} ; : 
else 
MessageBox (hWnd, “Could not open temp file.", 
“File Error", MB_OK) ; 
break ; 
case WM_COMMAND: Br /* process menu items */ 


switch (wParam) 
t 


” case IDM_DOIT: /* Use hit the "Do it" menu item */ 
~ " WDC = Getdc ChWnd) ; 
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hFileHandle = _lopen ("MYFILE.TXT", OF_READ). ; 
if (hFileHandle != -1) e 
t /* find file Length */ 
nFiletLong = Cint) _llseek (hFileHandle, OL, 2) ; 
/* return to beginning */ 
_tlseek ChFileHandle, OL, 0) ; 
/* read the data into “cReadBuf */ 
_“lread ChFileHandle, (LPSTR) cReadBuf, 
nFileLong) ; 
_lclose (hEileHandle) : 
} 
TextOut (hDC, 0, 0, cBuf, wsprintf (cBuf, 
- "Read string = %s", CLPSTR) cReadBuf)) ; 
ReleaseDC (hWnd, hDC) >; , 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
. PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ - 


return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return (OL) ; 


} 
_LCREAT mWin2.0 m8Win3.0 e8Win3l 
Purpose Creates a new disk file. 
Syntax int _Icreat(LPSTR lpPathName, int iAttribute); 
Description This function creates a new file if the specified file name does not already exist. If the file already 
exists, the file is opened and truncated to zero bytes. ° 
Uses This is the standard way to create a new disk file. OpenFile() is an alternative, if information 
about the file (date, full path name) is needed: . 
Returns int, the MS-DOS file handle for the file. Returns —1 on error. 
- See Also OpenFile(), _IcloseQ 
Parameters 
lpPathName LPSTR: A pointer to a null-terminated character string containing the file name. The string must 
contain characters from the ANSI character set (not the OEM/DOS character set). 
Attribute int: The DOS file attribute. This should be one of the attributes listed in Table 20-5. 


0 
1 
2 
3 


Névinal Both eee and “iting data is alowed 
Read-only. The file cannot be opened for writing data. 
Hidden. Not shown on a directory list. 

System. Not shown on a directory list. 


Table 20-5. DOS File Attributes. 


Example . 


See the example under the _Iclose() function description. 
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_LLSEEK 
| Purpose 

Syntax 

Description 


Uses 
Returns 

* See Also 
Parameters 


hFile 


lOffset 
iOrigin 
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mWin2.00 mWin3.0 wm Win3.l 


Moves to a new location in a disk file. 


- LONG _Iseek(int hFile, long lOffset, int Origin); 


_llseek() repositions a pointer in a file that was previously opened with either _Icreat(), 
_lopen(), or OpenFile(). The pointer marks the position at which the next _lread() and _lwrite() 
function calls will start. 


This function is the basis for all random-access file operations. The function can also be used to 
determine the length of a file. 


LONG, the offset in bytes from the beginning of the file to the file position pointer. The pointer 
points to the location at which the next _lread() and _lwrite() operations will bse 


_lopen(), ea _lwrite(), _Iclose(Q) 


int: The file handle. This is an integer value that DOS returns when a file is opened or created. 
The value is obtained by calling _lopen(), _Icreat(), or OpenFile(). 


LONG: The number of bytes the pointer is to be moved. 


“int: The starting position or direction to move the pointer. This can be any of the values listed in 


Table 20-6. 


Meaning — 


Table 20-6. 


Example. 


_LOPEN 
Purpose 
Syntax 
Description 


Uses 
Returns 
See Also 


Parameters 
lpPathName 


iReadWrite 


Moves the file ae [Offset pees from the panace of the file. 5 Setting both /Offset and iOnigin 
to zero moves the pointer to the beginning of the file. 


Moves the file pointer /Offset bytes from the current position in the file. 
Moves the file pointer /Offset bytes from the end of the file. 


_liseek() Position Values. 


See the example under the _Iclose() function description. 


mWin20 mWin3.0 mWin3l 
Opens a file for reading or writing data. 
int _lopen(LPSTR IpPathName, int iReadWrite); 


This is the normal function for opening an existing file for reading or writing data, OpenFile() 
can be used as an alternative if additional information is needed about the file (date created, 
etc.). Use _lcreat() to create a file for the first time. 


Called before _lread() or _lwrite() can be used to read or write data in the file. 
int, the MS-DOS file handle for the file. Returns —-1 on error, such as the file not being found. 
OpenFile(), _Iread(), _IwriteQ) 


LPSTR: A pointer to a null-terminated character string containing the file name. The string must 
contain characters from the ANSI character set (not the OEM/DOS character set). 


int: Specifies how the file is to be accessed. This can be any combination of the values i in ‘Table 
20-7, combined with the C language me OR operator (I). 
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OF_READ 
OF_READWRITE 
OF_SHARE_COMPAT 


OF_SHARE_DENY_NONE 
OF_SHARE_DENY_READ 
- OF_SHARE_DENY_WRITE 


OF_SHARE_EXCLUSIVE 


OF_WAITE 


The file is wid for reading only. 
The file is opened for reading and writing. 


~The file can be opened by any number of applications at the same time. The function will fail 
- (return --1) if the file has been opened previously with a different mode. This is called “compat: 
ibility mode.” 


The file can be opened by any number of applications at the same time. The function will fail 
(return -1) if the file has been opened previously in compatibility mode using 
OF_SHARE_COMPAT. 

Opens the file and denies other applications read access. The function will fait (return -1) if the 
file has been opened by another application for read access, or in a a mode using 
OF_SHARE_COMPAT. 


Opens the file and denies other applications write access. The function will fai (return -1) if the 
file has been opened by another application for write access, or in compatibility mode using 
OF_SHARE_COMPAT.. " 

Opens the file and denies other applications read or write access. The function will fail (return-1) 
if the file has been opened by another application or opened previously by the same application. 


‘Opens the file for writing only. 


Table 20-7. _lopen() Access Values. 


Example 


Syntax 
Description 


Returns 
See Also 
Parameters 
hFile 
lpBuffer 


wBytes 
‘Example 


LWRITE 


int _Iread(int hFile, LPSTR lpBuffer, int wBytes); 


See the example under the _Iclose() function description. 


BWin2.0 w8Wind.0 gmWind) 
Reads data from a disk file. Hl 


This function reads data from a disk file starting at the current file position pointer. When a file 


_ is initially opened by _lopen() or OpenFile(), the file pointer is set to the beginning of the file. As 


data is read using _lread(), the pointer moves forward by the number of bytes read. The pointer 
can be repositioned i in the file by calling _Ilseek(). 


int, the number of bytes actually read from the file. Returns ~1 on error. The returned value may 
be less than wByles if the end-of-file is detected during the read process. 


_lopen(), OpenFile(), _Iclose() 


int: The file handle. This is an integer value that DOS returns when a file is opened or created. 
The value is obtained by calling _lopen() or OpenFile(). 


LPSTR: A pointer to a memory buffer to hold the data read from the disk file. The buffer must be 
at least wBytes in length. . 


WORD: The number of bytes to read from the disk file. 
See the example under the _Ielose() function description. 


wi Win 3.1 


2 mWind.0) mWin3.0) om Wind. 


Purpose 
Syntax 


Writes data to a disk file. 


- int _lwrite(int hile, LPSTR lpBuffer, int wBytes);, 
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Description 


Returns 
See Also 


Parameters 
hFile 


lpBuffer 
wBytes 
Example 


OPENFILE 


Purpose 
Syntax- 
Description 


: 20. MS-DOS AND DISK FILE ACCESS v 


This funccion writes data from a disk file starting at the current file position pointer. When a file 
is initially opened by _lopen(), _Icreat(), or OpenFile(), the file pointer is set to the beginning of 
the file. As data is written using _|write(), the pointer moves forward by the number of bytes 
written. The pointer can be repositioned in the file by calling _Ilseek(). 


int, the number of bytes written to the file. Returns —1 on error. 
_lopen(), _Icreat(), OpenFile(), _Iclose() ; 


int: The file handle. This is an integer value that DOS returns when a file is opened or created. 
The value is obtained by calling _lopen(), _Icreat(), or OpenFile(). 

LPSTR: A pointer to a memory buffer that contains the data to be written to the disk file. 
WORD: The number of bytes to write to the disk file. 


See the example under the _Iclose() function description. 


BWin2.0 mWin3d0 mWin3.l 


Creates, opens, or deletes files. 
int OpenFile(LPSTR lpFileName, LPOFSTRUCT I[pReOpenBuf, WORD wStyle); 


Th,3 function combines a number of more primitive file initiation functions (such as _Icreat() 
and _lopen()) into a single powerful function. The function uses the OFSTRUCT data structure 
defined in WINDOWS.H as follows: 


typedef struct tagOFSTRUCT 
of : : 


‘BYTE | 
BYTE 
WORD 
BYE 
BYTE 


+ OFSTRUCT; 
typedef OFSTRUCT 
typedef OFSTRUCT NEAR 
typedef OFSTRUCT FAR 


Uses 


Returns 
See Also 


Parameters 
lpFileName 


lpReOpenBuf 


wsStyle 


cBytes; /* Length of OF struct */ 
fFixedDisk; /* non-zero if fixed drive */ 
nErrCode; /* MS DOS error ccde */ 
reserved(l4]; _/* file date and time */ 
szPathNamel128]; '/* full path name and */ 
-/* file name (OEM chars) */ 

*POFSTRUCT; 

*NPOFSTRUCT; 

*LPOFSTRUCT; 


OpenFile() includes options that will create a simple dialog box to display error messages 
automatically. — 


This is the standard way to create and/or open a disk file. It is the only direct way to delete a file 
from within Windows. 


int, the MS-DOS file handle. Keturns —1 on error. 
_lopen(), _Iclose(), _Icreat(). 


LPSTR: A pointer to a null-terminated character string that contains the name of the disk file. 


_ The characters should be from the ANSI (Windows default) character set. If the file name string 


contains OEM (MS-DOS) characters, use OemToAnsi() to convert the characters to the ANSI 


- character set before calling OpenFile(). 


LPSTR: A pointer to an OFSTRUCT data structure. The data fields i in this structure will be filled 
in after OpenFile() has been called. 


WORD: A flag to determine what OpenFile() i is to do. The flag values listed in Table 20-8 can be 
combined using the C language binary OR operator (1). 
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OF_CANCEL 
OF_CREATE 


‘ . OF_DELETE 


"OF_EXIST 
OF_PARSE 


”-OF_PROMPT 


OF_READ © 
OF_READWAITE 
OF_REOPEN 


‘OF_SHARE_ COMPACT 


_OF_SHARE_DENY_NONE 
OF_SHARE_DENY_READ 
OF_SHARE_DENY_WRITE 


- OF_SHARE_EXCLUSIVE 


OF VERIFY 


+ OF_WAITE 


Only used with the OF_ PROMPT style. Adds @Cancel button to the file- not-found dialog box. 
Creates a new fi fi le. If the file already exists, the fi le is truncated to zero bytes. 

Deletes a file. pare 

Checks if the file exists. The file is opened, and then immediately closed. 

Fills in the OFSTRUCT data structure, but does not open or close the file. Useful for determining » 
the full path name or file date/time. 

Displays a dialog box if the requested file does not exist. The dialog box requests that the user 
put a disk in drive A and retry. This is seldom a reasonable action. 


The file is opened for reading only. oa 
The file is opened for reading and writing. 


Opens the file specified in the szPathName field of the OFSTRUCT. This assures that the same 


| file is opened that was originally open when OpenFile() was first called. Otherwise, changing _ 


default directories could result in changing which of several files with the same name, but 
residing in different directories, isopened. : 
The file can be opened by any number of applications at the same time. The function wil fall 
(return -1) if the file has been opened previously with a aitierent mode. This i is called “compat- 
ibility mode.” 
The file can be opened by any number of applications at the same time. The function will fail 
(return -1) if the file has been opened previously in compatibility mode. 
Opens the file and denies other applications read access. The function will fail (return—1) if the 
file has been opened by another application for read access, or opened in compatibility mode. 
Opens the file and'denies other applications write access. The function will fail (retum -1) if the 
file has been opéned by another application for write access, or opened in compatibility mode. 
Opens the file and denies other applications read or write access. The function will fail (return - 
1) if the file has been opened by another application or has been opened previously by. Wh same 
application. 


Verifies that the date and time of the file on the disk are the. same as ‘the data i in the OFSTRUCT ° 


ae “data structure. This assumes that OpenFie() has aru been called at least once to fill in the 


data. 
" Opens the file for writing data Sali 


Table 20-8. OpenFile( ) Flag Values. 


Example 


This example uses OpenFile() twice. When the WM_CREATE - 
message is processed, the application creates a file called 
“MYFILE.TMP” using OpenFile(). Ten integers are written to 
the file. When the user clicks the “Do It!” menu item, 
OpenFile() is called again to open the file. The ten integers are 
__.Tead into an array, and displayed on the window's client area, 
_as shown in Figure 20-18. SetHandleCount() is also used in this. 


faa 
| CL 


Data Read From Disk 
0123456789 


Figure 20-13. OpenFile() 
Bonne 


f— generic 


example to allow the application to open as many as 50 files at 
one time. This maximum is not taken pavantadge of in- this oe example, which only has one file 
open at a time. : 
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Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ ; 


HDC noe 7 

OFSTRUCT of ; 

char ee 1281, « cReadBut C64) ; 

HANDLE hFileHandle ; 

int i, nStatus, nFileLong, nData C10] ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_CREATE: 

nStatus = SetHandleCount (50) ; 

if (nStatus != 50) 
MessageBox (hWnd, "Not able to open 50 files.", 

“Warning”, MB_OK) ; 

hFileHandle = OpenFile C"MYFILE. TMP", Sof, 
OF_CREATE) ; 

if (nStatus !=-1 Ba hFileHandle != -1) 

{ 


for (i =0 7; 1< 10; itt) /* write 10 ints */ 
_lwrite ChFileHandle, (LPSTR) &i, 
; sizeof Cint)) ; 
_lclose (hFileHandle) ; 


} 
else 
MessageBox (hWnd, "Could not open file.", 
“File Error", MB_OK) ; 
break ; 
case WM LS COHMAND: /* process menu items */ 


switch (wParam) 


case IDM_DOIT: /* veer hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
hFileHandle = Openfile Sere TMP", &of, 
OF_READ) ; 
if ChFileHandle 1s -1) 
{ /* find file Length in bytes */ 
nFileLong = Cint) _llseek ChFileHandle, OL, 2) ; 
/* return to beginning */ 
_tlseek ChFileHandle, OL, 0); 
/* file Length in integers */ 
nFileLong /= sizeof (int) ; _ 
/* read the data into array */ 
for (i = 0 ; i < nFileLong ; i++) 
_lread (hFileHandle, eight &nData Cid, 
pireat Cint)) ; 
_lclose ChFileHandle) ; 
} 
TextOut ChDC, 0, 0, "Data Read From Disk", 19) ; 
for (i = 0; i < nFileLong ; it+) 
TextOut ChDC, 15 * i, 20, cBuf, wsprintf (cBuf, 
"4d", nData £FiJ)) ; 
ReleaseDC (hWnd, hDC) ; 


break ; 
case IDM_QUIT: /* send end of application message */ 
, DestroyWindow (hWnd) ; 
break ; 2 
} 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; : si . 
defaults . /* default windows message processing */ 


return DefWindowProc (hWnd, iMessage, wParam, \Param) ; 
} . inn me 
return COL) ; 


799 


WINDOWS API BIBLE 


SETENVIRONMENT wWin20 mWin3.0 mWin3! 
Purpose Changes the environment variable settings for a port. . 
Syntax int SetEnvironment(LPSTR /pPortName, LPSTR lpEnviron, WORD nCount); 
Description Windows maintains a table of environment settings for each of the ports as a part of the GDI 
, (graphics device interface). These settings control the current port configuration, such as the 
baud rate and parity settings for a serial port. 
Uses — Changing the settings of a port. An application can redirect printer i to adisk fle by chang- 
. - ing the printer port’s environment string toa disk filename.  .ggmm aenene’ se TEP re 
Returns int, the number of bytes copied to the environment table. Zero = 3 : 
: ; Dolt! Quit 
on error, ~1 if the environment was deleted. SOuTE seni 
nv = wn, 
See Also GetEnvironment(), CreateDC() 
Parameters Figure 20-14. SetEnviron- 
lpPortName _ LPSTR: A pointer to a null-terminated character string con- ment() Bone 
taining the port name. Examples are “LPT!” and “COM2.” 
UpEnviron | LPSTR: A pointer to a null- terminated character string containing the new environment string. 
The WIN.INI file contains a number of examples of preset values for environment variables. 
nCount WORD: The number of bytes to be copied. 
Example This example, which is illustrated in Figure 20-14, loads and displays the current environment 


variable settings for the COMI device when the user clicks the “Do It!” menu item. If none have 
been set, the port is set to 9600 baud, no parity, 8-bit word length, and one stop bit. 


long FAR PASCAL WndProc CHWND hWnd, unsigned Mes eage yt WORD wParam, LONG lParam) 


£ 


HDC hDC ; 
char cBut ‘C1281, cEnv £643 ; 
int n€nvChar ; 
switch (iMessage) . /* process windows messages */ 
{ ; 
case: WM_ COMMAND: /* process menu items */ 
switch (wParam) : , 
' | case IDM. DoIT: -(/* User hit the "Do it" menu item 7 
AEnvChat = pe Ceavinonment C"COMI", cEnv, ons 
~ hDC.= GetDC (hWnd) ; 
TextOut ChDC, 0, 0, cBuf, wsprintf (cBuf, 
“COM1 Env = %s", (LPSTR) cEnv)) ; 
if’ (nEnvChar == 0% 
SetEnvironment ("COM1", "9600,n,8,1", 10) ; 
break ; : 
[Other program lines] 
SETERRORMODE mWin2.0 mw Win3.0 |B Win3.l 
Purpose, Sets whether or not Windows shows the default critical error message. 
Syntax WORD SetErrorMode(WORD wMode); . 
Description Windows uses MS-DOS for disk functions. DOS sends an INT 24H interrupt when a critical error 
: occurs, such as being unable to read a disk. This is where the dreaded message “Abort, Cancel, 
_ Retry?” message comes from under DOS. Windows has its own message box as a default critical 
: error handler. SetErrorMode() allows an application to turn this default message box on and off. 
Uses Usually, the error message box i is left on, except when the application i is doing file access and has 


its own error ais 


‘ : 


800. 


Returns 


Parameters 
wMode 


Example 
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WORD, the previous error mode. 0 if Windows was set to display the default critical error message _ 
box, 1 if not. , 


WORD: Set to 1 to shut off the default critical error message box. Set to 0 to turn it on. 


. This example shuts down the default critical error message box when the WM_CREATE message 


is processed. When the user clicks the “Do It!” menu item, the application attempts to open a file 
on the A drive. Assuming that the drive door kas been left open, a critical DOS error occurs. The 
normal Windows warning message box is not shown, so the application can go ahead and show its 


. OWN error message via the MessageBox() function. 


long FAR PASCAL WrdProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . 


PAINTSTRUCT - ps; . 

OFSTRUCT offile ; 

int n; 

switch (iMessage) /* process windows messages */ 


case WM_CREATE: : 
SetErrorMode (1) ; /* no error message */ 
break ; ;. 

case WM_COMMAND: | . 
switch (wParam) 
{ 


case IDM_DOIT: j 
n = OpenFile ("“A:Temp", &ofFile, OF_READ) ; 
if (n == -1) 
MessageBox (hWnd, 
“Could not read file on drive A:", 
“File Problem", MB_ICONHAND | MB_OK) ; 


break ; 
[Other program lines] 
SetHanpieCount | mWin2.0 8Win30  8Win3.l 
Purpose Changes the number of files an application can have open at once. -— 
Syntax ~ WORD SetHandleCount(WORD wNumber); \ 
Description The default number of files an application can have open at one time is 20. SetHandleCount() 
: allows this number to increase to any number up to 255. 
Uses Useful in disk-intensive applications, such as database programs. 
Returns WORD, the number of files that can actually be opened at one time. This may be less than 
wNumober if MS-DOS runs out of file handle space. 
See Also OpenFile() 
Parameters , 
wNumber WORD: The desired number of files that can be open at one time. The maximum is 255. 
Example See the example under the OpenFile() function description. 
WRITEPRIVATEPROFILESTRING as aWin20 gWin30 mWin3l 
Purpose — Copies a character string to an application’s private profile (.INI) file. 
Syntax - BOOL WritePrivateProfileString(LPSTR lpApplicationName, LPSTR lpKeyName, LPSTR 
lpString, LPSTR lpFileName); 
Description The best way for a program to “remember” user preferences, such as subdirectory names, is to 


write them to an initialization file. For items that may affect more than one application, this 
. # 
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. Uses 


Returns 
See Also 
Parameters 


should be the main WIN.INI file. For items that will affect only the application itself, this should 
be a private .INI file. WritePrivateProfileString() writes a character ene The string is assumed 
to be in a file with the format 


Capplication name] 
keyname = string 


The file is assumed to be in the Windows subdirectory (the subdirectory containing 


' WIN.EXE). A different subdirectory can be specified by using the full path name for /pFileName. 
' If the file is not found, a new one is created. If the application name is not found in the file, 


lpApplicationName is written to the file and enclosed in square brackets. If ages is not 
found, it is written to the file, followed by an equal sign. 


Writing and updating the application’s private .INI file. The values written in the .INI file can be 
both character strings and numeric values. Intéger values are written using the numeric charac- 


. ters as a string (eg., “124”). 


BOOL. TRUE if the function is successful, FALSE on error. 
GetPrivateProfileInt(), GetPrivateProfileString() 


lpApplicationName LPSTR: A pointer toa shames string that contains the application name in the private INI file. 


. lpKeyName 


lpString 


lpFileName 


Example 


This is the string that appears inside the square brackets. 

LPSTR: A pointer to the key name in the private .INI file. This is the string to the left of the equal 
sign. If lyKeyName is set to NULL, the entire section starting with lpApplicationName is de- 
leted. Comment lines (starting with a semicolon) are not deleted. 

LPSTR: The string value to write to the right of the equal sign. If/pString is NULL, the entire line 
starting with lpKeyName is deleted. 

LPSTR: A pointer to a character string containing the private .INI file name. The file is assumed 
to be in the Windows subdirectory unless a path name is include with the file name in 


_ lpFileName. 


See the example under the GetPrivateProfileInt() function description. 


WhiTEPROFILESTRING mWin2.0 wWin3.0 mWin3.l 


Purpose 
Syntax 
Description 


Uses 


Writes an entry to the WIN.INI file. 
BOOL WriteProfileString(LPSTR sslpnanoaNicnd LPSTR lpKeyName, LPSTR ipString); 


The best way for a program to “remember” user preferences, such as subdirectory names, is to — 
write them to an initialization file. For items that may affect more than one application, this 
should be the main WIN.INI file. For items that will affect only the apptication itself, this should 
be a private .INI file. WriteProfileString() writes a character string in WIN.INI. The string is 
assumed to be written with the format 
Capplication name] 
keyname = string 

_ WIN.INI is assumed to be in the Windows subdirectory (the subdirectory containing 
WIN.EXE). A different subdirectory can be specified by using the full path name for /pFileName. 
If the application name is not found, lpApplicationName is written to the file, and enclosed in 
square brackets. If pKeyName is not found, it is written to the file, and followed by an equal sign. 


Most often used as an application, to remember user settings, and file names. The value written 


_ to the .INI file can be either character strings or numeric values. Integer values are written to 


WIN.INI by writing the numeric characters in a string (eg., “124”). 
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Returns ‘BOOL. TRUE if the function is successful, FALSE on error. 
See Also GetProfileInt(), GetProfileString(), GetWindowsDirectory() 
Parameters . 


lpApplicationName LPSTR: A pointer to a character string that contains the application name in the WIN.INI file. 
This is the string that appears inside the square brackets. . 


lpKeyName LPSTR: A pointer to the key name in the WIN.INI file. This is the string to the left of the equal 
sign. If IpKeyName is set to NULL, the entire section starting with lpApplicationName is de- 
leted. Comment lines (starting with a semicolon) are not deleted. 


lpString © LPSTR: The string value to write to the right of the equal sign. If/pString is NULL, the entire line 
starting with lpKeyName is deleted. 
Example See the example under the GetProfileInt() function description. 
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Windows programs need to be able to communicate with external devices. The most common device is a printer. This 
specialized requirement is well supported in Windows, as described in Chapter 10, Device Contexts, Text Output, and 
Printing. Other important external devices are communications equipment, such as modems and instrumentation 
that may be connected to the computer via serial or parallel communications lines. Because of the wide range of 
external devices that can be connected to a computer, Windows cannot provide high-level support for every piece of 
equipment. Instead, the function library contains 16 low-level functions that provide the programmer with the basic 
tools for dealing with any device. 


Communications Support 


Communications support is not a trivial matter for Windows. Consider the case of a communications program that 
sends and receives data via a modem attached to the computer's serial port. The data from the modem arrives slowly 
(relative to the internal clock speed of the computer) and can arrive at any time. If the Windows program simply 
looped, checking for incoming data bytes, the program would take over the Windows environment. No other applica- 
tion could get the input focus. This violates the basic principle behind the structure of all Windows programs, which 
must give up control of the environment frequently to allow other programs to run. ; 

To get around this problem, the Windows function library includes interrupt-driven communications support. 
When the communications device receives an input byte, it generates a hardware interrupt. The interrupt briefly halts 
whatever application is running and stores the input byte in a memory buffer. Control is then immediately given back 
to Windows. 

The memory buffer i is ; called the “receive. data queue.” The data bytes accumulate in the queue as they are re- 
ceived. When a Windows communications application wants to read the incoming data, it reads the receive queue 
data. Data to be transmitted is also stored in a buffer before sais sent to the communications device. This buffer is 
called the “transmit data queue.” 


Figure 21-1. Communications Data Queues. 
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Figure 21-1 shows the organization of communications functions and data queues. The OpenComm() function 
opens up a communications link to an external device, such as a serial port, and sets up the transmit and receive data 
queues. Only one application can open a device at one time. The application retains control of the device until 
CloseComm() is called. The application that has control of the device uses the. WriteComm() function to send data to 
the device, and uses ReadComm() to read data received from the device. In both cases, the data is buffered via the 
data queues. For example, calling WriteComm() places the data in the transmit queue. Windows will send the data to 
the device when the device completes sending bytes already in the transmit queue. 

Two functions are provided which allow the normal first-in, first-out processing of data in the queues to be by- 
passed. TransmitCommChar() makes a character become the next character sent, which is useful for sending special 
control sequences, such as escape sequences. UngetCommChar() puts a character at the beginning of the receive 
queue. This character will be the next character read. This is convenient for programming applications that have 
multiple functions for processing incoming data. 


Reading Data in the Receive Data Queue 
As previously mentioned, the communications program cannot simply loop forever, checking for data in the data 
queues. The application must continually give up control to Windows so that other applications can run. There are two. 
approaches to checking the data queues from within a Windows program. The simplest way is to use a timer. The 
Windows timer can be set to generate a WM_TIMER message on a frequency of perhaps ten times per second. Each 
time the WM_TIMER message is processed by the application, the receive data queue can be checked with 
ReadComm() to look for data. , 

Although the timer approach will work, it is not the best way to design a communications program. A better way 
to write a communications program is to use a PeekMessage() loop for the program’s main message loop. Peek- 
Message() takes control if no other application is requesting it. This approach allows the communications program to 
continually check the receive data queue in the “gaps” when other Windows applications are not active. The example | 
programs under the function descriptions in this chapter all use the PeekMessage() approach. 

Writing a complete communications program requires an understanding of the several protocols in use for trans- 
mitting and receiving data. A good source of information is Practical Digital and Data Communications by Paul 
Bates (Prentice-Hall, 1987). This book covers both serial and paralle] communications: 


N 


Communications Function Summary 
‘fable 21-1 summarizes the Windows communication support functions, The detailed function descriptions are mn the 
next section. 


BuldCommDCe Convers a command eine in DOS MODE command oral to fill the fields i ina Device Control 


Block (DCB). . . 
ClearCommBreak Clears a communications device break state, restoring operation, 
CloseComm _- Closes a communications device. 
EscapeCommFunction Sets a communications device extended function. 
FlushComm Clears all data in a communications queue. ; 
GetCommeEnror Determines the error status of a communications port, and clears the error. 
GetCommEventMask Determines which communication event has occurred. 
GetCommState Determines the current settings of a communications device. 
OpenComm Opens a communications device (port) and allocates memory for the input and ai data 
queues. 
RealiComm Reads data from an open communications device. 
 SetCommBreak Temporarily suspends operation of a communications device. 
SetCommEventMask Sets which communications events are enabled. 
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Figure 21-1. continued 


“Function, <  ... - Purpose... Be Be | 
SetCommState . Changes the settings baud rate, etc.) for a communications device. 
TransmitCommcChar Sends a character to a communications device immediately, bypassing the transmit data 
queue. 
: UngetCommChar Places a character at the beginning of the receive data queue, bypassing any other characters 


already in the queue. 
WriteComm - Sends data to a communications device. e 


Table 21-1. Communications Function Summary. 


Communications Function Descriptions 
This section contains the detailed descriptions of the Windows communication functions. 


BurtpComMMDCB eWin2.0 m@Win30 weWin3l 


Purpose Converts a command string in DOS MODE command format to fill the fields | in a Device Control 
Block (DCB). 

Syntax int BuildCommDCB(LPSTR lpDef, DCB FAR * lpDCB); . 

Description The SetCommState() function requires that the configuration data for the communications port 


(baud rate, parity, etc.) be stored in a data structure of type DCB. BuildCommDCB() provides a 
convenient way to set the DCB elements based on a character string. The character string must 
be in the format used by the DOS MODE command. The DCB data structure is defined i in 


WINDOWS.H as: 
typedef struct tagDCB /* device control block (DCB) */ 
{ . : 
BYTE Id; /* Internal Device ID */ 
WORD BaudRate; /* Baudrate at which runing */ 
BYTE ByteSize; /* Number of bits/byte, 4-8 */ 
BYTE Parity; /* 0-4=None,0dd,Even,Mark,Space */ 
BYTE StopBits; /* 0,1,2 = 1, 1.5, 2 : ¥/ 
WORD RlsTimeout; /* Timeout for RLSD to be set */ 
WORD CtsTimeout; /* Timeout for CTS to be set */ 
WORD DsrTimeout; /* Timeout for DSR to be set */ 
BYTE fBinary: 1; : /* Binary Mode (skip EOF check */ 
BYTE fRtsDisable:1; /* Don't assert RTS at init time */ 
BYTE fParity: 1; /* Enable parity checking */ ~ 
BYTE fOutxCtsFlow:1; /* CTS handshaking on output */ 
BYTE fOutxDsrFlow:1; © /* DSR handshaking on output x) 
BYTE fDummy: 2; /* Reserved */ 
BYTE fOtrDisable:1; /* Don't assert DTR at init time */ 
BYTE fOutX: 1; : /* Enable output X-ON/X-OFF */ 
BYTE fInx: 1; 7 /* Enable input X-ON/X-OFF */ 
. BYTE fPeChar: 1; /* Enable Parity Err Replacement */ 

BYTE fNull: 1; /* Enable Null stripping */ 
BYTE fChEvt: 1; /* Enable Rx character event. */ 
BYTE fDtrflow: 1; /* DTR handshake on input */ 
BYTE fRtsflow: 1; : /* RTS handshake on input */ 
BYTE fDummy2: 1; 
char XonChar; /* Tx and Rx X-ON character */ 
char XoffChar; /* Tx and Rx X-OFF character ‘*/ 
WORD XonLim; /* Transmit X-ON threshold ' */ 
WORD XoffLim; ; /* Transmit X-OFF threshold */ 
char PeChar; /* Parity error replacement char */ 
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char EofChar; 

char EvtChar; 

WORD TxDelay; 
} DCB; 


Uses 
Returns 
See Also 


Parameters 
lpDef 


lpDCB 


Example 
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/* End of Input character */ 
/* Recieved Event character */ 
/* Amount of time between chars */ 


Note that two groups of the structure's elements are coded bit values, saving space. 
Used prior to SetCommState() to prepare the DCB data. 

int, zero if the lpDef string is translated, negative on error. 

SetCommState() 


LPSTR: A pointer to a character string in DOS MODE format. For example the string 
“com1:1200,e,7,1” establishes the port at 1200 baud, even parity, 7-bit word length, and one stop 
bit. 

DCB FAR *: A pointer to a DCB structure. The structure's elements will be initialized based on 
the /pDef string. It may be necessary to set additional values by directly initializing the DCB 
elements after BuildCommDCB() has been called. 


This example creates a primitive communications program. When the program first starts, COM1 
is opened for 1200 baud, even parity, 7-bit word length, and one stop bit. All of the characters the 
user types show up on the line marked “Out>.” Any characters received from COM1 show up on 
the line marked “In>,” including echoed characters. No formatting is done for the characters. 
Control characters such as CR/LF show up as vertical lines. 

Figure 21-2 shows a typi- 
cal log-on sequence. A Hayes 


; SE I ERS ES Gertericts ACME oom ea ees if a 
modem is connected to 
COMI. The Hayes modem 


In> ATDT6822633IN CONNECT 120081tIH 24WNCINIIEH ost Name: 
. Out> ATDT682263311 
command ATDT is used to = 


dial a phone number. Note Figure 21-2. Simple Communications Program Example. 
that the typed characters are 

echoed on the “In>” line. When a connection is made, the input line begins to show the charac: 
ters received from the remote computer. 

The program uses a PeekMessage() loop for the main program loop. This function allows for 
periodic checking of the input data queue using ReadComm(). If characters are in the queue, 
they are copied to the c/nBu/f buffer. A user message numbered WM_USER + 1 is posted to cause 
the WndProc() function to do the actual output of the received characters. 

Within the WndProc() function, the COM1 port is opened when processing the WM_CREATE 
message. Note that both the input and output data queues are flushed after the port is opened. A 
combination of BuildCommDCB() and SetCommState() is used to set the port to the desired 
baud rate, parity, etc. EscapeCommFunction() is demonstrated by sending a reset to the port. 
This is usually not necessary. 

User-typed characters for output to the port are handled by sending each typed character to 
the port using WriteComm(). The remainder of the logic in WndProc() displays character stings 
on the window’s client area. As soon as 80 characters are collected, the strings are erased and 
started again. The “Da It!” menu item toggles a temporary break in communications on and off. 
The communications break state is displayed in the program’s window caption. Note that the port 
is closed by CloseComm() as the program exits. 


/* generic.c simple com program example */ 
#include <windows.h> 


#include “generi 


static 
static 


c.h" 


int nComID = -1 ; 
char cInBuf £256 + 128], cOutBuf C128] ; 
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“qnt PASCAL WinMain (HANDLE hInstance, HANDLE hPreviInstance, LPSTR LpszCmdLine, int nCmdShow) 
{ . 


HWND hWnd ; 
MSG msg ; : 
WNDCLASS wndclass ; 
COMSTAT ComStat ; 
' char cBuf £128] ; 
int i, nReadChars, nStart ; 


ghInstance = hInstance ; 
if (!hPrevinstance) 


t 
wndclass.style = CS_HREDRAW | CS_VREDRAW ; 
wndclass.lpfnWndProc = WndProc ; 
wndclass.cbClsExtra =0; 
wndclass.cbWndExtra =O; 
wndclass.hInstance = hInstance ; 
wndclass.hicon = LoadiIcon (hInstance, gszAppName) ; 
wndclass.hCursor = LoadCursor CNULL, IDC_ARROW) ; 
wndclass.hbrBackground = GetStockObject (WHITE_BRUSH) ; 
wndclass.lpszMenuName = gszAppName ; 
wndclass.lpszClassName = gszAppName ; 
if (!RegisterClass (&wndclass)) 
return FALSE ; 
3} 
hWnd = CreateWindow ( /* create the program's window here */ 
gszAppName, , /* class name */ 
gszAppName, /* window name */ 
WS_OVERLAPPEDWINDOW, /* window style */ 
CW_USEDEFAULT, /* x position on screen */ 
CW_USEDEFAULT, | /* y position on screen */ 
CW_USEDEFAULT, ' /* width of window */ 
CW_USEDEFAULT, /* height of window */ 
NULL, /* parent window handle (null = none) */ 
NULL, /* menu handle (null = use class menu) */ 
hInstance, /* instance handle */ = 
NULL) ; /* Lpstr Cnull = not used) */ 
ShowWindow ChWnd, nCmdShow) ; 
UpdateWindow (hWnd) ; , 
‘while (TRUE) /* use peek message loop to check com */ 
if (PeekMessage (&msg, NULL, 0, 0, PM_REMOVE)) 
t ; . 
if (msg.message == WM_QUIT) 
break ; 
‘else 
{ 
TranslateMessage (&msg) -; 
DispatchMessage (&msg) ; 
} 
} & 


else if (nComID >= 0) /* check the com port for data */ 
if ((mReadChars = ReadComm (nComID, cBuf, 128)) > 0) 
{ ae 


if C(nStart = Lstrlen (cInBuf)) < 80) 
{ : /* add chars to end of string */ 
for (i = 0 ; i < nReadChars ; i++) 

_ _c¢InBuf CnStart + iJ] = cBuf Cid ; 
cInBuf CnReadChars + nStart] = 0 ; 
PostMessage (msg.hwnd, WM_USER + 1, 0, OL) ; 


else : , ‘ 
{ * start string over */ 
for (i =0 3; i < nReadChars ; i++) 
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cInBuf Cil = cBuf Cid ; 
cInBuf CnReadChars] = 0; 
PostMessage (msg.hwnd, WM_LUSER + 1, 1, OL) ; 


else 
GetCommError (nComID, &ComStat) ; 


} 
return msg.wParam ; 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
t : : 


PAINTSTRUCT ps > 

HDC hDC ; 

DCB dcb ; 

int i, nStatus ; 
char ‘ cBuf C128] ; © 
static BOOL bToggle = TRUE ; 


switch (iMessage) 


case WM_CREATE: 7 
nComID = OpenComm ("COM1", 128, 128) ; 
if (nComID < 0) 
MessageBox (hWnd, “Could not open COM1", “Warning”, 


MB_OK) ; 
else 
{ . 
FlushComm (nComiID, 0) ; /* empty output queue */ 
FlushComm (nComID, 1) ; /* eapty input queue */ 
BuildCommDCB ("com1:1200,e,7,1", &dcb) ; — 
SetCommState (&dcb) >; 
EscapeCommFunction (nComID, RESETDEV) ; 
MessageBox (hWnd, "COM1 is open.", "Message", 
MB_OK) ; | 
} Pa 
break ; 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
TextOut (ps.hdc, 0, 0, “In>", 3) ; 
TextOut (ps.hdc, 40, 0, cInBuf, Lstrlen (cInBuf)) ; 
TextOut (ps.hdc, 0, 20, “Out>", 4) ; 
TextOut (ps.hdc, 40, 20, cOutBuf, Istrlen (cOutBuf)) ; 
EndPaint (hwnd, &ps) ; 
break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: 
if (bToggle) 
{ 


bToggle = FALSE ; 
SetCommBreak (nComID) ; 
SetWindowText (hWnd, "Comm Break") ; 


else 
{ 
bToggle = TRUE ; 
ClearCommBreak (nComID) ; 
SetWindowText ChWnd, "Comm Open") ; 
} 
break ; 
case IDM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
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} 
break ; : 
case WM_CHAR: /* user typed a char */ 
if (nComID >= 0) 
{ 
nStatus = WriteComm (nComID, 7 
(LPSTR) &wParam, 1) ; 
if (nStatus < 0) 

MessageBox (hWnd, “Output comm error.", 
“Message”, MB_OK) ; 

else 
{ 
= ltstrlen (cOutBuf) ; 

if (i > 80)/* don't overflow Line size */ 

{ 
cOutBuf [0] = (char) wParam ; 
cOutBuf C1] =0 ; 

InvalidateRect éhund, NULL, TRUE) ; 

} 

else /* added char to end of typed string */ 

{ Y 
cOutBuf Cid = (char) wParam ; 
cOutBuf Ci+132=0; 
hDC = GetDC ChWnd) ; 

TextOut (hDC, 40, 20, cOutBuf, 
Lstrlen CcOutBuf)) ; 
. ReleaseDC (hWnd, hDC) ; 
} 2 

} ~ 
} 
else ; 

MessageBox (hWnd, "Click Do It! to connect.", 

“Message”, MB_OK) ; 

break ; 
case WM_USER + 1: /* need to update screen from input */ 
switch (wParam) 
{ 
case 0: - /* input chars added to end of string */ 
hDC = GetDC (hWnd) ; 

TextOut (hdc, 40, 0, cInBuf, lstrlen (cInBuf)) ; 

ReleaseDC (hWnd, hDC); 

break ; ; 

case 1: /* started string over from start */ 
InvalidateRect (hWnd, NULL, TRUE) ; 
; break ; 
} 
break ; ; 
case WM_DESTROY: /* stop application */ 


CloseCommn (nComID) ; 
POs caul thes sage co)” . 


break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
} 
CucarComMBReaAK Win2.0  m@Win3.0  mWin3.] 
Purpose _ Clears 2 a communications device break state, restoring g operation. , 
Syntax int ClearCommBreak(int nCid); 
Description Communications devices (parallel and serial ports) can be ‘athpoearily turned off by calling 
SetCommBreak(). ClearCommBreak() clears the break state, restoring the port’s operation. Data 
remaining in the input and output data queues is not affected. 


Uses It is simpler to use SetCommBreak() to temporarily close a communications device than to close 
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~ CLRRTS 
RESETDEV 
SETDTR 
SETRTS 
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and then reopen the port. 


Returns int, zero if the function was successful, negative on error (such as 7Cid not being a valid device). 

See Also SetCommBreak(), OpenComm() | 

Parameters 3 

nCid int: The communications device ID value. This is the value returned by OpenComm(). 

Example See the previous example under the BuildCommDCB() function description. 

CiLosEComMM Win2.0 mWin30 mWin3.1 

Purpose Closes a communications device. 

Syntax int CloseComm(int nCid); 

Description This function closes the communications device previously opened by OpenComm(), and frees 
the memory associated with the input and output data queues. Any data in the output queue is 
sent before the device is closed. Only one application can have a port open at any one time. 

Uses Any application that opens a communications device must call CloseComm() to return the port 
to the system. Failure to do this will cause the port to be inaccessible to other applications. 

Returns int, zero if the communications device (port) is closed, negative on error. 

See Also OpenComm() 

Parameters 

nCid int: The ID of the device to be closed. This is the value returned by OpenComm() when the device 

. was first opened. 

Example See the example under the BuildCommDCB() function description. 

EscaPpECOMMFUNCTION . mWin20 mWin30 mWin31 

Purpose — Sets a communications device extended function. . : 

Syntax int EscapeCommF unction(int nCid, int nFunc); 

Description This function provides a convenient way to send a communications device a control code, such as 
DTR, RTS, or XON/OFF. 

Uses DTR and RTS signals are used in establishing communications links between two devices. XON/ 
OFF pairs are used in sending packets of data betiveen two devices, . 

Returns int, zero if the function is successful, negative on error. 

See Also OpenComm() 

Parameters 

nCid int: The ID of the device to be closed. This is the value returned by OpenComm() when the device 
was first opened. : 

nFunc int: The function code. This can be any of the codes listed in Table 21-2. 


S aemteanaamennenel 


Clears the data-terminal-ready (DTR) signal. 
Clears the request-to-send (RTS) signal. 
Attempts to reset the device. 

Sends the data-terminal-ready (DTR) signal. 
~ Sends the request-to-send (RTS) signal. 
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Table 21 -2. continued 


SETXOFF Emulates receipt of an XOFF character. 
SETXON : Emulates receipt of an XON character. 


. Table 21-2. Communications Codes. 


Example See the example under the BuildCommDCB() function description. 

FLusHCoMM mWin2.0 eWin30 mWin31 

Purpose Clears all data in a communications queue. 

Syntax dint FlushComm(int nCid , int nQueue); 7 

Description Windows uses memory buffers to store incoming and outgoing data for a communications device 
(port). FlushComm() is used to clear the buffers. 

Uses Used when the communications device is first opened with OpenComm(). It can also be used 

within the communications program logic if iti is desirable to purge the queues. 

Returns. int, zero if the queue was cleared, negative on error. 

See Also OpenComm() 

Parameters | 

nCid int: The communications device ID value. This is the value returned by OpenComm(). 

nQueue int: Set to zero to clear the transmit data queue. Set to one to clear the receive data queue. 

Example See the example under the BuildCommDCB() function description. 

GETCOMMERROR i mWin2.0 eWin3.0  mWin3.! 

Purpose Determines the error status of a communications port, and clears the error. 

Syntax int GetCommError(int »Cid, COMSTAT FAR */pStat); . 

Description Windows locks a communications device (port) when an error is detected. The port remains 


locked until GetCommError() is called. The error data is copied to the COMSTAT data structure. 
This structure is defined in WINDOWS.H as follows: 


typedef struct tagCOMSTAT 
{ 


BYTE fCtsHold: /* Transmit is on CTS hold */ 


BYTE fDsrHold: Me /* Transmit is on DSR hold */ 
BYTE fRisdHold: 1; /* Transmit is on RLSD hold */ 
BYTE fxXoffHold: 1; /* Received handshake */ 
BYTE fXoffSent: 1; - /* Issued handshake */ 
BYTE fEof: 1; /* End-of-file character found */ 
BYTE fTxim: 1; /* Character being transmitted */ 
“WORD cbhInQue; /* count of characters in Rx Queue */ 
‘WORD cbhOutQue; : /* count of characters in Tx Queue */ 
} COMSTAT; 
/ Note that the first seven elements of the COMSTAT data structure are bit rales 
Uses Used to unlock the communications device and determine the error status. 
Returns int, the error code returned by the most recently used communications function. This can be any 


of the error codes listed in Table 21-3. 
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CE, BREAK 


CE_CTSTO 


CE_DNS 
CE_DSRTO 


CD_FRAME 

- CD_IOE 
CD_MODE 
CE_OOP 
CE_OVERRUN 
CE_PTO 
CE_RLSDTO 


CE_RXOVER 


CE_RXPARITY 
CE_TXFULL 


A break condition was detected. 

Clear-to-send time-out. The amount of time before time-out is set by the CisTimeout element of 
the DCB data structure passed to SetCommState{ ). See BuildCommDCB({) for the DCB 
structure definition. 


Parallel device not selected. 


Data-set-ready time-out. The amount of time before time-out 1s set by the DsrTimeout element 
of the DCB data structure passed to SetCommState(). se BuildCommDCB() for the DCB 
structure definition. 
Hardware framing error detected. 
Input/Output error on a parallel device. ; 
The requested communications mode is not supported by the device, or nCid is not valid. 
The parallel device is out of paper. 
~ Acharacter arrived before the last character could be read. The character is lost. 
Parallel device time out. 


Receive-line-signal-detect time-out. The amount of time before time-out is set by the 
RisTimeout element of the DCB data structure passed to SetCommState(). See Build- 
CommDCB() for the DCB structure definition. 


The receive queue overflowed. This can also be set by having a character be received after the 
end-of-file character has been set. The end-of-file character is determined by the EofChar 
element of the DCB data structure passed to SetCommsState( ). See BuildCommDCB() for the 
_DCB structure definition. 
. A parity error was detected. 


The transmit queue is full. 


Table 21-3. Communications Error Codes. 


See Also BuildCommDCB(), SetCommState() 

Parameters ; 

nCid int: The communications device ID value. This is the value returned by OpenComm(). 

lpStat COMSTAT FAR *: A pointer to a COMSTAT data structure. The structure will be filled with the 
current device status. 

Example “See the example under BuildCommDCB(). 

GetTComMEVENTMaASk Win2.0 mWin3.0 mWin31 

Purpose Determines which communication event has occurred. 

Syntax WORD GetCommEventMask(int nCid, int nEvtMask); 

‘Description Events are noncharacter communication data, such as clear-to-send (CTS) line status. The events 
“which will be detected for a device are set with SetCommEventMask(). GetCommEventMask() 

_ determines which event has occurred. Each event is coded as a bit flag. 
Uses ~- Used within the message loop (or timer message processing function) to determine the event 


status of a communications device (port). 2 . ‘ 
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Returns 


WORD. The event status for each type of event is coded as a bit in the returned WORD. Each of the 
event flags is given a name in WINDOWS.H as listed in Table 21-4. 


EV_BREAK 
EV_CTS 

- EV_DSR 
EV_ERR 
EV_PERR ~ 
EV_RING 

~ EVRLSD 
EV_RXCHAR 
EV_RXFLAG 

~ EV_TXEMPTY 


Break detected on input. 

Clear-to-send (CTS) signal change detected. 

Data-set-ready (DSR) signal change detected. 

Line-status error detected. They are CE_FRAME, CE_! OVERRUN, and CE_RXPARITY. 
Printer error detected. They are CE_NDS, CE_IOE, CE_ LOOP, and CE_PTO. 

Ring indicator detected. 

Receive-line-signal-detect (RLSD) change detected. 

Any character placed in the receive queue was detected. 

The event character was received and placed in the receive queue. 

The last character in the transmit queue has been sent. 


Table 21-4. Communications Event Flags. 


See Also SetCommEventMask() 
Parameters 
nCid int:. The communications device ID value. This is the value returned by OpenComm(). 
nEviMask int: Sets which events are to be monitored after the call to GetCommEventMask(). nEpiMask 
can be any combination of the bit flags in Table 21-4, combined with the C language binary OR 
operator (1). Set nHvtMask to OxFFFF to monitor all events. 
Example See the example under the SetCommEventMask() function description. 
GETCOMMSTATE | eWin2.0 m&Win30 mWin3.1 
Purpose Determines the current settings of a communications device. = a 
Syntax int GetCommState(int nCid, DCB FAR*/pDCB); 
_ Description. This function copies the current settings for a communications Serial Port: 
device (serial or parallel port) to a DCB data structure. ed Boa nates cere S 
Uses Determining the settings for a communications device, such as 
the current baud rate. Figure 21-3. GetComm- 
Returns int, zero if the function was successful, negative on error. State() Example. — 
: See Also SetCommState(), BuildCommDCBQ(), OpenComm() 
‘Parameters - 
nCid int: The communications device ID value. This is the value returned by OpenComm(). 
lpDCB DCB FAR *: A pointer to a DCB (Device Control Block) data structure. See the BuildCommDCB(). .- 
function description for the definition of this structure. 
Example This example, which is illustrated in Figure 21-8, opens the COM1 and LPT! ports and displays 


the initial settings when the user clicks the “Do It!” menu item. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 


HDC hdc ; 
- char cBuf £128] ; 
int nComm ; 
DCB deb; \ 
/ switch (iMessage) /* process windows messages */ 
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{ 
case WM_COMMAND: /* process menu ttems */ 
Switch (wParam) 
{ ; . 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC (hWnd) ; 
nComm = OpenComm ("COM1", 128, 128) ; 
GetCommState (nComm, &dcb) ; 
TextOut ChDC, 0, 0, “Serial Port:", 12) ; 
TextOut (hDC, 10, 20, cBuf, wsprintf (cBuf, 
"ID = %d, Baud Rate = %d, Parity = %d", 
dcb.Id, dcb.BaudRate, dcb.Parity)) ; 
CloseComm (nComm) ; . 
nComm = OpenComm ("LPT1", 0, O) ; 
GetCommState (nComm, &dcb) ; 
TextOut (hDC, 0, 40, "Parallel Port:", 14) ; 
TextOut (hDC, 10, 60, cBuf, wsprintf (cBuf, 
“Ip = %d",dcb.Id)) ; 
CloseComm (nComm) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
[Other program lines] 
OrpeENComM aWin2.0 mWin30 mWin3.1 
Purpose Opens a communications device (port) and allocates memory for the input and output data 
queues. ‘ 
Syntax int OpenComm(LPSTR /pComName, WORD winQueue, WORD wOuiQueue); 
Description Before a communications device can be used, it must be opened. The device will be opened with 
default settings for baud rate, parity, etc. These settings can be changed by using 
BuildCommDCB() and SetCommState(). Serial ports use data buffers called “queues” to tempo- 
rarily store data being sent and received by the port. OpenComm() also allocates memory for the 
input and output data queues. Parallel ports do not use data buffers. The winQueue and 
wOutQueue values will be ignored if a parallel port is being opened. Only one application can 
open a communications device at a time. Be sure to call CloseComm() when the device is no 
: longer needed. 
Uses OpenComm() must be called before a communications device, such as a serial or parallel port, 
can be used. 
Returns int, the ID value of the opened communications device. This value should be saved in a static 


variable. If an error occurs in opening the device, the function returns one of the negative values 
listed in Table 21-5. . 


“Meaning: ©. 


IE_BADID ~ An invalid device name. 


IE_BAUDRATE Unsupported baud rate. t 
IE_BYTESIZE Unsupported byte size. : 

{E_DEFAULT Error in the default parameters. 

IEHARDWARE Hardware not present. _ 

IE_MEMORY Unable to allocate memory for the data queues. 

IE_NOPEN _ _ Not able to open the device. 

IE_OPEN - Device already open. 


Table 21-5. OpenComm() Error Codes. 
See Also CloseComm(), BuildCommDCBQ), SetCommState(), WriteComm() 
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Parameters oe 
lpComName LPSTR: A pointer to a null-terminated character string containing the device name. Examples 
are “COMI” and “LPT2.” The valid device numbers start with 1, and are limited by the number of 
. devices on the system. . 
winQueue WORD: The size of the receive data queue. For serial devices, this is ope set at 1,024 bytes. 
For parallel devices, the value is ignored. 
wOutQueue WORD: The size of the transmit data queue. For serial devices, this is ‘auieay set at 128 bytes. 
For parallel devices, the value is ignored. 
Example See the example under BuildCommDCB(). 
ReEaADCoMM BWin2.0 mWin30 mWin31 
Purpose Reads data from an open communications device. 
Syntax int ReadComm(int nCid, LPSTR lpBu/, int nSize); 
Description With a serial communications device, input data is stored temporarily in a data queue as it is 
cae received. ReadComm() reads the data queue and copies the data into a buffer pointed to by 
lpBuf, removing the data from the,data queue. With a parallel communications device, only one 
data byte is available at any one time. This value is read and copied to the buffer pointed to by 
IpBuf. 
Uses Reading data from a communications device previously opened by OpenComm(). 
Returns int, the number of characters actually read. This number will be smaller than nSize if the data 
: queue contains fewer than nSize bytes. If the returned value is equal to nSize, more than nSize 
bytes may be in the data queue and the queue should be read again with ReadComm(). Ifan error 
occurs, the returned value will be negative. The absolute value of the returned value will be the 
number of characters read. Use GetCommError() to retrieve the error code. It is a good practice 
to call GetCommError() every time ReadComm() returns zero to clear any possible errors on a 
serial device. For parallel devices, the returned value. is always zero. 
See Also Cretan: GetCommError() 
Parameters 
nCid ~ int: The communications device ID value. This is the value returned by OpenComm(). — 
lpBuf LPSTR: A pointer to the data buffer to receive the data. The buffer must be at least nSize bytes 
long. 
nSize int: The maximum number of bytes to read from the data queue. 
Example See the example under BuildCommDCB(). 
SerCoMMBReEAK — gWin20 mWin30 mWin31 
Purpose Temporarily suspends operation of a communications device. . 
Syntax int SetCommBreak(int 2Cid); 
Description This function shuts down character transmission to and from a communications device. The de- 
vice is left in the break state until ClearCommBreak() is called. Data sent to the transmit data 
queue is stored in the queue, but it is not transmitted until the break state is cleared. 
Uses Setting the communications device in a break state i is simpler for temporary interruptions than | 
; closing and then reopening the device. 
Returns - int, zero if the; break state i is established. negative on error (such as an invalid nCid value). 
. See Also ClearCommBreak0), OpenComm() 
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Parameters 

nCid int: The communications device ID value. This is the value returned by OpenComm(). 

Example See the example under the BuildCommDCB() function description. 

SeTComMEventTMask mWin2.0  mWin3.0  mWin3.1 

Purpose Sets which communications events are enabled. 

Syntax WORD FAR *SetCommEventMask(int Cid, WORD nEviMask), 

Description Events are noncharacter communication data, such as the DSR (Data Set Ready) signal state. 
This function allows certain events to be screened. Use GetCommEventMask() to retrieve the 
event status. 

Uses Used in low-level control over a port’s signal status. 

Returns WORD FAR *, a pointer to a WORD that contains the bit mask for the event status. The event has 

occurred if the bit is set tol. 

See Also GetCommEventMask(), GetCommError() 

Parameters oe oo oe oa 

nCid int: The communications device ID value. This is the value returned by OpenComm(). 

nEviMask int: The bit mask for the events to be enabled. This can be any combination of the values in Table 


21-6, combined with the C language binary OR operator (I). 


EV_BREAK . Breaks are é tetecied 0 iat 

EV_CTS . Clear-to-send (CTS) signal changes are detected. 

EV_DSR . Data-set-ready (DSR) signal changes are detected. 

EV_ERR _ Line-status errors are detected. They are CE_FRAME, CE_OVERRUN, and CE_RXPARITY. 
EV_PERR | Printer errors are detected. They are CE_NDS, CE_IOE, CE_LOOP, and CE_PTO. 
EV_RING - Ring indicator is detected. 

EV_RLSD. Receive-line-signal-detect (RLSD) changes are detected. 

EV_RXCHAR | Any character placed in the receive queue is detected. 

EV_RXFLAG : The event character is received and placed in the receive queue. 

EV_TXEMPTY The last character in the transmit queue has been sent. 


Table 21-6. Communications Event Flags. 


Example This example is similar to the OO 
simple communications program  jiEgaaameeliae sa a generic: ts os cata 
under the BuildCommDCB() func- Do lt! Quit 
tion description. In this case, Set- In> HCONNECT 12000111 27WNCIIliHost Name: 
CommEventMask() is used to Out>ATDT682263311 

- enable both break and CTS signal  [EM@ormask 0x0 
changes for the communications Figure 21-4, SetCommEventMask() Example. 
port. Communications events are 
detected in the program’s message loop. The current event mask is displayed in the window’s 
~ client area by sending a WM_USER + 1 message to WndProc(). WndProc() intercepts this mes- 
sage; and displays the error mask on the third line, as shown in Figure 21-4. 
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/* generic.c 


#include <windows.h> 
#Hinclude “generic.h" 


‘static 
static 


int 
char 


nComID = -1 ; 


simple serial communications application */ 


cInBuf C2561, cOutBuf £128] ; 


int PASCAL WinMain CHANDLE hInstance, HANDLE hPrevinstance, LPSTR lpszCmdLine, int nCmdShow) 


{ 


HWND 


hWnd ; 
MSG msg ; 
WNDCLASS wndclass ; 
COMSTAT ComStat ; 
char cBuf £128) ; 
WORD wComError ; 
int i, nReadChars, nStart ; 


ghInstance = hInstance ; 
if (thPrevinstance) 


{ 


} 


hWnd = 


wndclass.style 
“wndclass.lpfnndProc 

wndclass.cbClsExtra 
wndclass.cbWndExtra 
.wndclass.hInstance 
wndclass.hicon 
wndclass.hCursor 
wndclass.hbrBackground 
wndclass.LpszMenuName 
wndclass.lpszClassName 


if (!RegisterClass (&wndclass)) 
return FALSE ; 


CreateWindow ¢ 
gszAppName, 
gszAppName, 
WS_OVERLAPPEDWINDOW, 
CW_USEDEFAULT, 
CW_USEDEFAULT, 
CW_USEDEFAULT, 
CW_USEDEFAULT, 
NULL, 

NULL, 
hInstance, 
NULL) ; 


ShowWindow (hWnd, nCmdShow) ; 
UpdateWindow (hWnd) ; 


while (TRUE) 


{ : 


/* store instance handle as global var. 


CS_HREDRAW | CS_VREDRAW ; 
WndProc ; ; 

0; 

0; 

hInstance ; 
Loadicon (hInstance, gszAppName) ;- 
LoadCursor (NULL, IDC_ARROW) ; 
GetStockObject CWHITE_BRUSH) ; 
gszAppName ; 

gszAppName ; 


haw tb ow tm Wo ow 


/* create the program's window here */ 


‘/* class name */ 


/* 
/* 
{* 
[* 
7* 
/* 
/* 
/* 
/* 
[* 


window name */ 

window style */ 

x position on screen */ 

y position on screen */ 
width of window */ 

height of windew */ 

parent window handle (null = 
menu handle Cnull = 
instance handle */ 
Lpstr (null = not used) */ 


none) */ 
use class menu) */ 


#/ 


/* use peek message Loop to check com! */: 


if (PeekMessage (&msg, NULL, 0, 0, PM_REMOVE)) 


{ 
‘if (msg.message == WM_QUIT) 
break ; 
else ; 
t ; . 
TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} 
} P 
else if (nComID >= 0) 
C ee ae 


if ((nReadChars = 
{ 
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/* check the com port for data */ 


ReadComm (nComID, cBuf, 128)) > 0) 


{ 


} 


} 


21. COMMUNICATIONS FUNCTIONS V 


if ((nStart = Lstrlen (cInBuf)) < 80) 
{ /* add to end */ 
for €i = 0 ; i < nReadChars ; itt) 
cInBuf CnStart + iJ = cBuf cid ; 
cInBuf CnReadChars + nStart] =0 ; 
PostMessage (msg.hwnd, WM_USER + 1, 0, OL) 


“eo 


} 
else - 
¢ /* start string over */ 
for (1 = 0 ; i < nReadChars ; it+) 
cInBuf Cil = cBuf Ci] ; 
cInBuf CnReadChars] = 0; 
PostMessage (msg.hwnd, WM_USER + 1, 1, OL) ; 
} 
} 
else /* clear error, post mesg. to disp.-error */ 
{ 
GetCommError (nComID, &ComStat) ; 
wComError = GetCommEvéntMask (nComID, OxFFFF) ; 
PostMessage (msg.hwnd, WM_USER + 1, 2, 
CLONG) wComError) ; 
} 3 


return msg.wParam ; 


PAINTSTRUCT 


HDC 
DCB 
int 


_char 


static 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


Ps; 

hdc ; 

dcb ; 

i, nStatus ; 

cBuf C128] ; 
BOOL bToggle = TRUE ; 


switch (CiMessage) 


{ 


case WM_ 


case WM_ 


case WM_ 


CREATE: 
nComID = OpenComm ("COM1", 128, 128) ; 
if (nComID < 0) 
MessageBox (hWnd, “Could not open COM1", "Warning", 


MB_OK) ; 
else 
¢ 
FlushComm (nComID, 0) ; /* empty output queue */ 
FlushComm (nComID, 1) ; /* empty input queue */ 
BuildCommDCB ("comi:1200,e,7,1", &dcb) ; 
SetCommState (&dcb) ; 
SetCommEventMask (nComID, EV_BREAK | EV_CTS) ; 
MessageBox (hWnd, "COM1 is open.", "Message", 
MB_OK) ; 
} 
break ; 
PAINT: 


BeginPaint (hWnd, &ps) ; 

TextOut (ps.hdc, 0, 0, "In>", 3) ; 

TextOut (ps.hdc, 40, 0, cinBuf, lstrten (cInBuf)) ; 
TextOut (ps.hde, 0, 20, "Out>", 4) ; : 
TextOut (ps.hdc, 40, 20, cOutBuf, istrlen (cOutBuf)) ; 
EndPaint (hWnd, &ps) ; 


break ; ; 

COMMAND: /* process menu items */ 

switch (wParam) 

t 

case IDM_DOIT: /* put ESC into receive queue */ 
break ; . 

case IDM_QUIT: /* send end of application message */ 
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. DestroyWindow (hWnd) ; 
& break ; 
} 
break ; 
case WM_CHAR: ; /* user typed a char */ 
if (nComID >= 0) 
{ 


nStatus = WriteComm (nComID, (LPSTR) &wParam, 1) ; 

if (nStatus < 0) 

MessageBox (hWnd, “Output comm error.", 
“Message", MB_OK) ; 

else 

{ o 

i= strlen (cOutBuf) ; 

if Ci > 80) /* don't overflow line size */ 


cOutBuf [OJ = 
cOutBuf (1) = 
InvalidateRec 


(char) wParam ; 

0; 

t (hWnd, NULL, TRUE) ; 
else /* added char to end of typed string */ 


cOutBuf CiJ = (char) wParam ; 

cOutBuf Ci +13=0; 

hDC = GetDC (hWnd) ; 

TextOut ChDC, 40, 20, cOutBuf, 
istrlen (cOutBuf)) ; 

ReleaseDC ChWnd, hDC) ; 


} 
break ; ; 
case WM_USER + 1: ; /* need to update screen from input */ 
a, 4 switch (wParam) , : 
case 0: . /* input chars added to end of string */ 
hOC = GetDC ChWnd) ; : 
TextOut (hDC, 40, 0, cInBuf, Lstrlen (cInBuf)) ; 
ReveaseDC ChWnd/ hDC) ; , 
. break ; 
/* started string over from start */ 
InvalidateRect (hWnd, NULL, TRUE) ; 
break ; - 
case 2: /* display an error value */ 
hDC = GetDC ChWnd) ; 
TextOut (hDC, 0, 40, cBuf, wsprintf (cBuf, 
ne “Error mask Ox%x", LOWORD (lParam))) ; 
ReleaseDC. ChWnd, hDC) ; 
break; 
} 
break ; ae 
case WM_DESTROY: /* stop application */ 
CloseComm (nComID) ; : 
PostQuitMessage (0) ; 
break ; : ; 
default: . /* default windows.message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 


return (COL) ; 


SeTCoMMSTATE «| : eWin20 mWin30 mWin31 
Purpose ~ Changes the settings (baud rate, etc.) for a communications device. 


Syntax int SetCommState(DCB FAR */pDCB); 
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When a communications device is initially opened with OpenComm(), the default settings for the 


Description 
device are in place. SetCommState() allows these values to be changed. The new values are 
passed in a data structure of type DCB. This structure is typically initialized using Build- 
CommDCB(). The port ID value that SetCommState() is determined by is the ID element of the 
DCB structure. SetCommState() does not affect the input and output data queues. 

Uses Changing the settings for a communications device, such as the baud rate and parity for a serial 
port. \ 

Returns int, zero if the settings were changed, negative on error. 

See Also BuildCommDCB() 

Parameters 

lpDCB DCB FAR *: A pointer to a DCB (Device Control Block) data structure that contains the settings 
to use for the communications device. See the BuildCommDCB() description for a listing of the 
DCB structure. 

Example See the example under the BuildCommDCB() function description. 

TRANSMITCOMMCHAR mWin2.0° mWin3.0 mWin3.l 

Purpose Sends a character to a communications device immediately, bypassing the transmit data queue. 

Syntax int TransmitCommChar(int Cid, char cChar); 

Description Normally, characters are sent to a communications device (port) by using WriteComm() to copy 
characters to the transmit data queue, and then having Windows send the characters when the 
port is available. TransmitCommChar() places a character at the head of the queue, so that it is 
the next character sent. Only one character can be sent at a time using TransmitCommChar(). 
The function will return a negative (error) value if the previous character sent by Transmit- 
CommChar() has not been sent to the device. ‘ 

Uses Used to send special characters out of normal transmission sequence, For example, an external 

device may respond to an ESC or CAN (ASCH 27 or "94) character by resetting or starting a new 
mode. 

Returns int, zero if the character was sent, negative on error. 

See Also WriteComm() 

Parameters 

nCid int: The communications device ID value. This is the value returned by OpenComm(). 

cChar char: The character to be transmitted. | 

Example: This example creates a primitive communications program. The program is similar to one de- 


/*®* generic.c 


scribed under the BuildCommDCB() function description, but it is modified to demonstrate 
TransmitCommChar() and UngetCommChar(). Communications are to and from the COMI se- 
rial port. When the user clicks the “Do It!” menu item, an ESC character is placed at the end of 
the receive data queue by a call to UngetCommChar(). The ESC is the next character displayed 
on the window’s client area (displayed as a vertical line). 

When the user presses the key cap key, the ESC character is sent directly to COM1, bypassing 
any other characters in the transmit data queue. Do this by using TransmitCommChar() to send 
ESC, rather than using WriteComm() as is used for all other characters. This logic is typical of _ 
dealing with an external serial device that used the ESC character to force a reset or change the 
device state. 


generic windows application a 


#include <windows.h> 


H#include ' 


‘generic.h" 
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static 
static 


{ \ 
HWND hWnd ; 
MSG msg; 
WNDCLASS wndclass ; 
COMSTAT ComStat ; 
char cBuf £128] ; 
int i, nReadChars, nStart ; 
ghInstance = hInstance ; /* store instance handle as global var. */ 
if C!hPrevinstance). : 
{ 
wndclass.style = CS_HREDRAW | CS_VREDRAW ; 
wndclass.lpfnWndProc = WndProc ; 
wndclass.cbClsExtra =O; 
wndclass.cbWndExtra =0; 
wndclass.hInstance = hInstance ; 2 
wndclass.hIcon = LoadiIcon ChInstance, gszAppName) ; 
wndclass.hCursor = LoadCursor (NULL, IDC_ARROW) ; 
wndclass.hbrBackground = GetStockObject (WHITE_BRUSH) ; 
wndclass.lpszMenuName = gszAppName ; 
wndclass.lpszClassName = gszAppName ; 
if ('RegisterCtass (&wndclass)) 
return FALSE ; 
} 


int 
char 


nComID = -1 ; 


hWnd = CreateWindow (¢ 


cInBuf €256 + 1281, cOutBuf £128] ; 


int PASCAL WinMain (HANDLE hInstance, HANDLE hPrevInstance, LPSTR lpszCmdLine, int nCmdShow) 


create the program's window here */ 


gszAppName, /* class name */ 
gszAppName, /* window name */ 
WS_OVERLAPPEDWINDOW, /* window style */ 
CW_USEDEFAULT, .- /* x position.on screen */ 


CW_USEDEFAULT, 
CW_USEDEFAULT, 


y position on screen */ 
width of window */ 


CW_USEDEFAULT, /* height of window */ 

NULL, /* parent window handle Cnull-= none) */ 
NULL, , /* menu handle (null = use class menu) */ 
hInstance, /* instance handle */ ; 

NULL) ; /* tpstr (null = not used) */ 


~ ShowWindow ChWnd, nCmdShow) ; 


UpdateWindow (hWnd) ; 


while (TRUE) 


/* use peek message loop to check com1 */ 


{ 
if (PeekMessage (&msg, NULL, 0, 0, PM_REMOVE)) 
{ : 
if (msg.message ==.WM_QUIT) 
: break ; : 
else ‘ 
a _ 7 
TranslateMessage (&msg) ; 
is DispatchMessage (&msg) ; 
} - 
} 
else if (nCom1D >= 0) _/*® check the com port for data */ 
{ 


if ((nReadChars = ReadComm (nComID, cBuf, 128)) > 0) 
Cr. iss one oe fee a 
if (CnStart = lstrlen (cInBuf)) < 80) 
{- /* add chars to end of string */ 
for (i = 0; i < nReadChars ; i++) 
cinBuf CnStart + iJ = cBuf Cid ; 
cInBuf CnReadChars + nStart] =0 ; 
PostMessage (msg.hwnd, WM_USER + 1, 0, OL) ; 
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} 


} 


else 


} 


return msg.wParam ; 
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} 
else ‘ 
{ /* start string over */ 

for (i = 0 ; i < nReadChars ; i++) 

cInBuf Cild = cBuf Cil ; 

cInBuf CnReadChars] = 0 ; 

PostMessage (msg.hwnd, WM_USER +1, 1, OL) ; 
} 


GetCommError CnComID, &ComStat) ; 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


{ 


PAINTSTRUCT 


HDC 
ocB 
int 
char 
static 


BOOL 


switch (CiMessage) 


{ ‘ 


case WM_CREATE: 


ps ; 

hdc ; 

dcb ; 

i, nStatus ; 
cBuf £128] ; 
bToggle = TRUE >; 


nComID = OpenComm ("COM1", 128,.128) ; 
if (nComID < 0) ; 


else 
{ 


} 
break ; 


case WM_PAINT: 


MessageBox (hWnd, "Could not open COM1", "Warning", 


MB_OK) ; 


FlushComm (nComID, 0) ; %/* empty output queue */ 
FlushComm (nComiId, 1) ; /* empty input queue */ 


BuildCommDCB (“com1:1200,e,7,1", &dcb) ; 
SetCommState (&dcb) ; 

EscapeCommfunction (nComID, RESETDEV) ; 
MessageBox (hWnd, “COM1 is open.", "Message", 


MB_OK) ; 


BeginPaint (hWnd, &ps) ; 

TextOut (ps.hdc, 0, 0, “In>", 3) ; 

TextOut (ps.hdc, 40, 0, ciInBuf, Lstrlen (cInBuf)) ; 
TextOut (ps.hdc, 0, 20, “Out>", 4) ; 

TextOut (ps.hdc, 40, 20, cOutBuf, Istrten (cOutBuf)) ; 
EndPaint Chuind, &ps) ; 


break ; 


case WM_COMMAND: 


/* process menu items */ 


switch (wParam) 


{ 


case IDM_DOIT: /* put. ESC into receive queue */ 


UngetCommChar (nCom1I0, 27) ; 
break ; 


case IDM_QUIT: 


} 
break ; 


case WM_CHAR: 
if (nComID >= 0) 


{ 


DestroyWindow (hWnd) ; 
break ; 


/* user typed a char */ 


if (wParam == 27) /* ESC char - send direct */ 


nStatus = TransmitCommChar (nComID, 
(char) wParam) ; 
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else '7¢* all other chars go into queue */ 
nStatus = WriteComm (nComID, 
CLPSTR) &wParam, 1) ; 
if (nStatus <0) | 
MessageBox (hWnd, "Output comm error.", 
"Message", MB_OK) ; 


else 
{ 
i= lstrlen (cOutBuf) ; 
if (i > 80) /* don't overflow Line size */ 
{ 
cOutBuf CO] = (char) wParam ; 
cOutBuf [1] =0; 
InvalidateRect (hWnd, NULL, TRUE) ; 
} 
else /* added char to end of typed string */ 
{ ; 
cOutBuf Cid = (char) wParam ; 
cOutBuf Ci+11=0; 
hDC = GetDC (hWnd) ; 
TextOut ChDC, 40, 20, cOutBuf, 
tstrlen (cOutBuf)) ; 
ReleaseDC ChWnd, hDC) ; 
} : 
} 
} 
break ; 
case WM_USER + 1: /* need to update screen frem input */ 
switch (wParam) ? ‘ ; 
{ 
case 0: /* input chars added to end of string */ 
hDC = GetDC (hWnd) ; 
TextOut (hDC, 40, 0, cInBuf, Lstrlen (cInBuf)) ; 
ReleaseDC (hWnd, hDC ) ; 
break ; . 
_ case 1: /* started string over from start */ 
InvalidateRect (hWnd, NULL, TRUE) ; 
break ; 
} # 
break ; 
case WM_DESTROY: /* stop application */ 


CloseComm (nComID) ; 
PostQuitMessage (Q) ; 


break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
>. 
return (OL) ; 
} 
UnceTCommMCuar et | mWin2.0 wWin3d.0 mWind1 
Purpose Places a character at the beginning of the receive data queue, bypassing any other characters - 
already in the queue. ° . 
Syntax int UngetCommChar(int nCid, char cChar); 
Description Normally, characters are read from the receive data queue in the order that they were received 


using ReadComm(). UngetCommChar() allows a character to be placed at the beginning of the 
data queue. This character will be the next character read by ReadComm(). Only one character 
can be placed at the start of the receive data queue at a time. If the last character placed by 
UngetCommChar() has not been read, the next call to UngetCommChar() will return a negative 
(error) value. ; 
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Uses 


Returns 
See Also 


Parameters 
nCid 


cChar 
Example 


WriTECoMM 
Purpose 

Syntax 
Description 


Uses 
Returns 


See Also 


Parameters 
nCid 


lpBuf 
nSize 
Example 


21. COMMUNICATIONS FUNCTIONS ¥ 


This function is convenient if the program deals with certain characters as special markers. For 
example, a program might read each character received looking for an ESC character. When the 
ESC is received, it is put back on the receive queue, and then a separate function within the 
program is called to deal with the sequence of characters starting with ESC. 


int, zero if the character was placed at the start of the transmit data queue, negative on error. 
ReadComm() 


int: The communications device ID value. This is the value returned by O(penComm(). 
char: The character to be placed at the beginning of the receive data queue. 
See the previous example under the TransmitCommChar() function description. 


wWin2.0 mWin30 mWin3l 
Sends data to a communications device. 
int WriteComm(int nCid, LPSTR lpBu/, int nSize); 
This function sends a group of characters to a communications device. The data is copied to the 
transmit data queue, and then sent in the background while Windows processes the data request 
interrupts from the device. If the number of characters to be sent is larger than the space avail- 
able in the transmit data queue, data in the transmit queue will be lost. Use GetCommError() to 
determine the space in the transmit queue. 


Sending data to a communications device, such as a serial port. 


int, the number of characters transmitted. If an error occurs, the value will be negative, and have 
an absolute value equal to the number of characters sent. Use GetCommError() to determine the 
error type and clear the device's error status. 


OpenComm() 


int: The communications device ID value. This is the value returned by OpenComm(). 
LPSTR: A pointer to the buffer containing the data to be transmitted. 

int: The number of characters to be written. 

See the example under the BuildCommDCB() function description. 
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. Atom Functions 


A common programming problem is determinirg if a character string belongs to a group of strings. For example, a 
compiler will need to check each word in the source code listing against the set of commands and function names, If 
a match is found, the compiler knows that the word is part of the language. If not, the compiler must assume that it is 
a new variable name or constant. 

With any reasonably sized program, comparing each word to all of the commands and function names on a char- 
acter-by-character basis is unacceptably slow. Compilers use hash table techniques to reduce the number of compari- 
sons to a manageable number. Windows provides a similar facility in the form of atom functions. A group of character 
- strings can be loaded into an atom table. Each string is identified with a unique integer value. Because only integer 
values need to be compared, checking to see if a new string exists in the atom table is quick. Atoms are also useful for 
exchanging character data between running applications. 


Atom Tables 


Windows implements two types of atom tables, local atoms ia global atoms. Local atoms are stored in the 
application’s local memory block. (This is the 64K memory segment that is private to the application.) Only one local 
atom table is allowed per application. The table is created using the InitAtomTable() and AddAtom() functions. The 
table remains in existence until either all of the elements of the table have been deleted using DeleteAtom(), or until 
the application terminates. 

Global atoms are stored in the global memory area. Windows maintains one global atom table at all times. This 
table is shared by every application running on the system. Any application can add new elements (atoms) to the ~ 
global atom table using GlobalAddAtom() and can delete them using GlobalDeleteAtom(). There is no equivalent to 
InitAtomTable() for the global atom table, as the global table is always in existence if Windows is running. 

If the same character string is added to an atom table more than once, the string is not duplicated. Instead, a 
counter called the “reference count” of the atom is incremented. Each time the same string is added, the reference 
count goes up by one. Every time the same string is deleted, the reference count is reduced by one. When the refer- 
ence count is reduced to zero, the string (atom) is removed from the atom table. 

. The FindAtom() and GlobalfindAtom() functions determine if a character string has already been loaded in the 
atom table. These functions are fast. Of course, the program must load all of the comparison strings into the atom 
table before the search can be started. Using atom tables for string searches makes sense if the same group of strings 
will be searched a large number of times. 

If the application knows the atom value (the unique integer tag) for the string, the character string can be 
recovered with GetAtomName() or GlobalGetAtomName(). Because the atom values are integers, they can be passed 
between parts of a program as parameters in function calls. For example, a program can load all of the error and 
warning messages into a local atom table. The atom number for the string to display can then be used to pass the 
string to a message display function. 


Atom Data Structure 


Normally, you will not deal directly with the atom data. The atom functions provide all the needed functionality for 
adding, finding, and removing entries. If you need to deal directly with the atom data, the format used internally by 
Windows is 
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typedef struct tagATOMENTRY 
{ 
WORD wReserved ; 


int nRefCount ; /* the number of times the string has been added */ 
BYTE cStrLen ; , /* the Length of the string in bytes */ 
char cContent C11; /* the string characters (length variable) */ 


} “ATOMENTRY ; 


; Q . 

This structure is not defined in WINDOWS.H. The number of bytes in the cContent element is arbitrary, as it will 
vary depending on the string stored. The GetAtomHandle() function will retrieve a handle to the memory block con- ~ 
taining data in this format. 


Data Exchange 


A useful property of the global atom table is that it is available to all applications running on the system. This availabil- 
__ ity allows one program to load a string into the atom table, and another to pull it out. Because the atom’s unique value 
is a 16-bit number, atoms can be transmitted between running applications as the wParam part of a Windows mes- 
sage. This transmission requires that both the sending and receiving applications know the same message ID to use to 
transmit the atom value.. The RegisterWindowMessage() takes care of determining a unique message ID value to use. 
This message ID is then posted with the atom value as wParam using PostMessage(), and is received by the second 
application through the normal message loop and WndProc() function. The receiving application uses the wParam 
value to recover the string from the global atom table using GlobalGetAtomName(). 

The techniques for exchanging character strings between applications described above are demonstrated in the 
example program under the GlobalAddAtom() function. These simple techniques work fine if you are writing both the 
sending and receiving applications. The more general case is when you may want to send data to another 
programmer’s application, or receive data from that application. Working with other applications requires 2 consis- 
tent protocol for sending and receiving data, walelns is defined in the Dynamic Data Exchange (DDE) protocol, covered 
in Chapter 30. 


Atom Function Summary 
Table 22-1 summarizes the atom functins. The detailed function descriptions are in the next section: 


AddAtom Adds a character string to the application's local atom table. 


DeleteAtom | Deletes an item from the local atom table. 

FindAtom ‘Determines if a character string has been stored in the local atom table. 
GetAtomHandle ~ Retrieves a local memory handle to the memory area containing an atom. 
GetAtomName Retrieves the character string, given the atom's value. 

GlobalAddAtom Adds a character string to the global atom table. 

GlobalDeleteAtom Removes a character string from the global atom table. 

GlobalFindAtom _ Determines if a character String is stored in the global atom table. 
GlobalGetAtomName Retrieves a character string from the global atom table. 

InitAtomTable Initializes the local, atom table. 


Table 22-1. Atom Function Summary. 


Atom Function Descriptions | 
This section contains the detailed descriptions of the atom functions. 
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AppAToM 


@Win2.0 wmWin3d0 w8Win3.l 


Adds a character string to the application’s local atom table. 


Purpose 
- Syntax 
_ Description 


Uses 
Returns 


See Also 
Parameters 


lpString 


Example 


ATOM AddAtom(LPSTR /pString); 


This function is used to add entries to the local atom table. Each string is given a unique identi- 
fier called an atom. This atom is a 16-bit unsigned integer. If an exact copy of the string pointed to - 
by lpString already exists in the atom table, the existing entry's reference count (number of 
duplicates for the string) is increased by one. Note that atoms are not case-sensitive. The maxi- 


- mum string length i is 256 characters. 


Atom tables are a convenient way to store and retrieve character strings. 


ATOM, the string’s unique identifier. The returned value will be in the range 0xC000 to OxFFFF, 
Returns NULL on error. 


InitAtomTable() 


LPSTR: A pointer to a null-terminated character string that 
will be added to the local atom table. | . 


This example, which is illustrated in Figure 22-1, loads six. 
character strings into the local atom table when the program 
first starts (VM_CREATE message processed). Two of the 
strings are duplicates. The atom values for the six strings are 
stored in an array of ATOM values. When a WM_PAINT mes- °- 
sage is processed, the atom table is displayed. The string con- Figure 22-1. AddAtom() 
tents are retrieved from the atom table using the GetAtom Example. 

Name() function. To retrieve the reference count for each 

string, the local memory area containing the atom is locked. The memory area contains data in 
the structure ATOMENTRY format. This daia structure is defined at the top of the listing. 

When the user clicks the “Do It!” menu item, the application deletes atom number 3. As this 
atom starts with a reference count of two (it was duplicated), the first call to DeleteAtom() 
simply reduces the atom’s reference count by one. The second time the “Do It!” menu item is 
clicked, the atom is deleted by setting the atom value to zero. Atom 4 remains valid with a refer- _. 
ence count of i. 


— : qenerig 0° “fe [* 


‘fAtom 0, Ref Count 1> First String 
Atom 1, Ref Count 1> Second String 
Atom 2, Ref Count 1> Third String 

‘ {Atom 3, Ref Count 2> Fourth String 
Atom 4, Ref Count 2> Fourth String 
Atom 5, Ref Count 1> Last String 


typedef struct tagATOMENTRY 
{ 


WORD 
int 
BYTE 
char 
} ATOMENTRY ; 


wReserved ; 
nRefCount ; 
cStrLlen ; 
cContent [1] ; 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, ‘LONG lParam) 
r¢ fe 


PAINTSTRUCT ps ; 
char ; cBuf C128], cAtomContent [32] ; 
char *cNames [6] = ("First String", *»Second String", 
“Third String", “Fourth String", “Fourth String", 
“Last String} ; 
static ATOM AtomArray £6] ; 
WORD i, wAtom ; 
HANDLE hMem ; 
ATOMENTRY *AtomEntry ; 
" -switch CiMessage) /* process windows messages */ 
{ . 


case WM_CREATE: a ; , 
InitAtomTable (NULL) ; /* initialize local atom table */ 
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for (i=0; 1<6; it+) 
AtomArray [il = AddAtom (cNames [i]) ; 
break ; 
case WM_PAINT: , 
BeginPaint (hWnd, &ps) ; 
for (i1=0;1<6; itt) 
t 


wAtom = GetAtomName (AtomArray Cil, 
; cAtomCont-nt, 32) ; 
if CwAtom) 
¢ j 
hMem = GetAtomHandle CAtomArray Cil) ; 
AtomEntry = CATOMENTRY *) LocalLock (hMem) ; 
TextOut (ps.hac, 0, i*20, cBuf, wsprintf (cBuf, 
“Atom 4d, Ref Count %d> %s", 
AtomEntry->nRefCount, 
CLPSTR) cAtomContent)) ; 
LocalUnlock (hMem> ; 


} 
else 
TextOut (ps.hde, 0, i*20, cBuf, wsprintf (cBuf, 
“Atom 4d is no longer valid", i)) ; 
} . 
EndPaint (hWnd, &ps) ; 
break ; ; 
7 case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* delete atom 43 */ 
if (AtomArray (31) 
sé 
hMem = GetAtomHandle (AtomArray [3]) ; 
. AtomEntry = CATOMENTRY *) LocalLock (hMem) ; 
if CAtomEntry->nRefCount > 1) 
DeleteAtom (AtomArray [3]) ; 
else 
AtomArray £3] =0 ; 
LocalUnlock (hMem) ; 
} 
InvalidateRect ChWnd, NULL,/TRUE) ; /* force paint *, 
break ; 


-case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: 
PostQuitMessage (0) ; 


break ; 
default: 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 

} 

DELETEATOM | mWin2.0 mWin3.0 mWin3.1 

Purpose Deletes an item from the local atom table. 

Syntax ATOM DeleteAtom(ATOM nAtom); 

Description Each time the same character string is added to the atom table using AddAtom(), that entry's 
reference count is increased by one. DeleteAtom() reduces the reference count by one. When the 
entry’s reference count is reduced to zero, the string is removed from the local atom table. 

Uses . Removing strings from the local atom table. The entire local atom table will be removed from 
memory when the application is terminated, so it is not necessary to delete each atom prior to. 
stopping the program. 
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Returns 
See Also 


Parameters 
nAtom 


Example 


FINDATOM 
Purpose 
Syntax 
Description 


Uses 
Returns 


See Also” | 
Parameters 


lpString 


Example 


ATOM. NULL if the function was successful. The nAtom value is returned on error. 
AddAtom() 


ATOM: The atom to be deleted. This is the value returned by AddAtom(). 
See the previous example under the AddAtom() function description. 


| mWin20 mWin3.0 
Determines if a character string has been stored in the local atom table. 
ATOM FindAtom(LPSTR /pString); 


This function searches the local atom table for a case-insensitive match to the string pointed to 
by [pString. If a match is found, the atom’s value is returned as a 16-bit value. 


Locating a string in the atom table. 


ATOM, the 16-bit atom value. for the atom containing the requested string. NULL if the tine 
pointed to by pString has not been loaded into the local atom table by AddAtom(). 


AddAtom() . 
— generic [~ [= 
Do It! Quit 


/|Found <Third String>. 


Figure 22-2. FindAtom() 
Example. 


@ Win 3.1 


LPSTR: A pointer to a null-terminated character string con- 
taining the string to locate in the local atom table. 


This example loads six character strings into the local atom 
table when the program starts (WM_CREATE message re- 
ceived). When the user clicks the “Do It!” menu item, the table 
is searched for the string “Third String.” When the string is 
located, the result is displayed in the window's client area, as shown in Figure 22-2. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ , 


HDC 
char 
char 


WORD 


switch (iMessage) 
{ 


[Other program lines] 


hDC > : 
cBuf £1283, cAtomContent (€32] ; 
*cNames (6) = ("First String", "Second String", 
"Third String", “Fourth String", “Fourth String: 
“Last String} ; 
i, wAtom ; 


/* process windows messages */ 


case WM_CREATE: 
InitAtomTable (NULL) ; 
for (i =0 3; 1<6; i++) 
AddAtom (cNames Cil); 


/* initialize local atom table */ 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) . 
case IDM_DOIT: /* aeXete atom a3 */ 

hDC = GetDC (hWnd) ; 

wAtom = FindAtom Third String") ; 

if (wAtom) 

TextOut (hDC, 0, 0, 
: “Found <Third String>.", 21) ; 

else 
Texcout Choc, 0, 0, 
"Did nee find <Third String>. My 80) .¢ 
ReleaseDC chind, hDC) ; 
break ; 


830° 


GETATOMHANDLE aWin2.0 mWin3.0 

Purpose Retrieves a local memory handle to the memory area containing an atom. 

Syntax HANDLE GetAtomHandle(ATOM wAtom); 

Description When a character string is added to the local atom table with AddAtom(), the data is stored in 
local memory in a data structure with the following format: 
typedef struct tagATOMENTRY 
: dacs 

WORD wReserved ; 
int nRefCount ; 
BYTE cStrLlen ; 
chet cContent C1] ; 
} ATOMENTRY ; 

; ‘This structure is not defined in WINDOWS.H. The array size of the cContent element is arbi- 
trary. The maximum length of an individual atom string is 256 characters. Windows’ total atom 
storage space is limited by the size of the local memory area (64K). GetAtomHandle() returns a 
handle to the memory area containing the ATOMENTRY data structure. The application can use 
this structure to determine the reference count of an atom. This is the number of times the same 
string was added to the local atom table using AddAtom(). 

Uses Seldom used. Normally, GetAtomName() is used to retrieve the contents of the atom’s string. 
GetAtomHandle() can be used to determine the reference count of an atom, if atom entries are 
being added and deleted from the atom table as the application runs. 

Returns HANDLE, a local memory handle. This handle can be used to lock the ATOMENTRY memory 

a block by calling LocalLock(). 

See Also GetvommameQ, AddAtom() 

Parameters 

wAtom _ ATOM: This is the atom number returned by AddAtom(). 

Example See the example under the AddAtom() function description. 

GETATOMNAME mWin2.0 mWin3.0 mWin3.1 

Purpose Retrieves the character string, given the atom’s value. . 

Syntax WORD GetAtomName(ATOM nAtom, LPSTR lpBuffer, int nSize); 

Description . This function copies the atom’s character string to the lpBuffer memory buffer, given the atom’s 

value. The atom’s value is the value returned by AddAtom() when the string was added to the 
local atom table. 

Uses - This is the normal way to retrieve an atom’s string. 

Returns WORD, the number of characters copied to /pBuffer. Returns zero if the atom is not valid. 

See Also GetAtomHandle(), AddAtom() 

Parameters 

nAtom ATOM: This is the 16-bit atom value returned 5 AddAtom() when the character string was _ 
added to the local atom table. 

lpBuffer LPSTR: A pointer to a memory buffer that will receive the character string. The buffer must be at 
least nSize bytes long. 

nSize int: The maximum number of characters to copy to the buffer pointed to by IpBuffer. 

Example See the example under the AddAtom() function description. 
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@ Win 3.1 
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GLOBALADDATOM | mWin2.0 mWin30 mWin3l 


Purpose Adds a character string to the global atom table. 
Syntax ATOM GlobalAddAtom(LPSTR pString); 
Description . The global atom table is shared by all running applications. GlobalAddAtom() adds a character 


string to the table. If the string already exists, the reference count for the atom (number of times 
the string has been stored) is increased by one. The maximum string length is 256 characters. 


Uses Storing a string in the global atom table makes the string available to any application that has the 


atom value (the returned value from this function is the atom value). This is a way to exchange 
character data between applications. 


Returns . ATOM, the atom value for the stored string. NULL on error. oe atom value will 1 be between 
. 0xC000 and OxFFFF. 

See Also GlobalGetAtomName(), GlobalDeleteAtom() © 

Parameters | . . 

lpString _LPSTR: A pointer to a character string containing the string to be added to the global atom table. 

Example _ This example demonstrates using globa: atoms to exchange string data between running applica- 


tions. The demonstration is most effective if two or more instances of the program are running at 
once. When the “Do It!” menu item on any of the program instances j is clicked, all of the instances 
display the string “Got>Transmitted data” at once. 

The program uses two important keys to communications hetwieen applications: registering a 
unique message and using the global atom table to store chardcter strings. The Register- 
Wind¢ «Message() creates a unique message ID value that will be the same for each program that 
requests the message ID. GlobalAddAtom() loads the character string into the global atom table 
that is accessible to all applications. 

_ When the user clicks the “Do It!” menu item, the program posts the u unique message to all 
running applications. The wParam value is set equal to the atom value returned by | 
GlobalAddAtom(). The —1 for the window handle in the PostMessage() call does the trick of 
sending the message to every window. Because the message is unique, only applications which 
called RegisterWindowMessage(‘“generic”) will have the message ID value to respond. 

When the unique message is received, the application uses 
the wParam value passed with the message to read the string ere 
back from the global atorn table. GlobalGetAtomName() recov- gua MMLLLG [e[e 


ers the string, allowing it to be displayed in the window’s client Do It! Quit 


area, as shown in Figure 22-3. Note that the atom is deleted [Got>Transmitted data 
from the global atom table when the program exits. This step is 


necessary, as the global atom table remains in place after the Figure 22-3. GlobalAdd- 
program terminates. | Atom( ) Example. 


long FAR PASCAL WndProc CHWND hWnd, ase ney iMessage, WORD wParam, LONG lParam) 
{ 


HDC hDC ; 

char cBut’ (1281, cAtomContent [32] ; 

static | WORD whessageID ; 

static . .-° ATOM AtomID ; 

switch (iMessage) /* process windows messages */ 
{ ; “+3 


case WM_CREATE: 
wMessageID = RegisterWindowMessage Co aenee te. 2 . 
AtomID = GlobalAddatom C"Transmitted data") ; 
break ; 

case WM COMMAND: vs 
switch (wParam) \ 


\ ~ 
; via process menu items */ ~ 
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case IDM_DOIT: \ 
PostMessage (-1, wMessageID, AtomID, OL) ; 
break ; 

case IDM_QUIT: 
DestroyWindow (hWnd) ; 
break ; 

} 

break ; 

case WM_DESTROY: 
GlobalDeleteAtom (AtomID) ; 
PostQuitMessage (0) ; 


break ; 
default: 
if (iMessage == wMessageID) /* registered message? */ 
{ \ 
hDC = GetDC (hWnd) ; 
GlobalGetAtomName (wParam, cAtomContent, 32) ; 
TextOut (hDC, 0, 0, cBuf, wsprintf (cBuf, 
"Got>%s", (LPSTR) cAtomContent)) ; 
ReleaseDC (hWnd, hDC) ; 
} 
else 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
} 
GLOBALDELETEATOM © . mWin2.0 mWin30 mWin3.1 
Purpose Removes a character string from the global atom table. 
Syntax ATOM GlobalDeleteAtom(ATOM nAtom); 
Description If a character string has been added to the global atom table more than once with the Global- 
; AddAtom() function, the atom’s reference count will be more than one. Calling Global- 
‘DeleteAtom() reduces the reference count by one. When the reference count is reduced to zero, 
the atom is deleted from the global atom table. 
Uses _ Atoms added to the global table by an application should be deleted before the application termi- 
nates. Otherwise, they will remain in memory for the duration of the Windows session. 
Returns ATOM. NULL if the function was successful. The nAtom value will be reuumnet if the function 
fails, indicating that 2Atom is not a valid atom. 
See Also GlobalAddAtom() 
Parameters 
nAtom ATOM: The atom value for the string to delete. This is the value returned by GlobalAddAtom(). 
Example See the previous example under the GlobalAddAtom() function description. 
GLOBALFINDATOM . WWin2.0 = =mWin3.0 = mWin3.l 
_ Purpose . Determines if a character string is stored in the global atom table. 
| Syntax ATOM GlobalFindAtom(LPSTR [pString); 
Description The global atom table is shared by all running applications. GlobalFindAtom() is used to deter- 
: mine if a character an has been loaded into the global atom table. The search is case-insen- 
sitive. 
Uses Normally not used. Usually, the atom values are stored and/or exchanged between app ieatons, 
rather than the character strings. 
Returns 


ATOM the atom value for the string i in the global atom table. NULL if the string is not-loaded in 
the atom table. 
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{ 


} mare | 
_return (OL) ; . Co 


See Also GlobalAddAtom() 

_ Parameters - 
lpString LPSTR: A pointer to a character string containing the string to locate in the global atom table. 
Example 


This example demonstrates the passive exchange of string data between running applications. It 


is most effective if two instances of the program run at the 
same time. The first time the “Do It!” menu item on any of the 
applications is clicked, the atom containing the string “Test 
String” is not found. This is because it has not been added to 
the global atom table. After the message “Test String Not 
Found” is displayed, the string is added to the global atom 


table. Any instance of the program that has the “Do It!” menu Figure 29-4. GlobalFind 
item clicked after that point will display the message shownin Atom() Example. 


Figure 22-4,“Test String Found.” 


Note that the program calls GlobalDeleteAtom() as many times as the atom was added to the 
global atom table. This is necessary to reduce the atom’s reference count to zero, if the. “Do It!” 
menu item has been clicked more than once. Each running instance of the program ends up 
deleting as many reference counts as it added. When the last instance of the program is termi- 


nated, the atom is certain to be removed from the global atom table. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 


HDC hoc ; 
char cBuf £12813, cAtomContent [32] ; 
ATOM Atom ; 
static int nCount = 0; 
int i; 
switch (iMessage) /* process windows messages */ 
{ 5 
case WM_COMMAND: /* process menu items */ . 


switch (wParam) 
{ 


case IDM_DOIT: 
ADC = GetDC ChWnd) ; 
Atom = GlobalFindAtom ("Test String") ; 
‘if CAtom) 
TextOut Choc, 0, 0, 
“Test String Found. ", 18); 
Zl se : 
TextOut Choc, 0, 0,° 
"Test String Not Found.", 22) ; 
GlobalAddAtom ("Test String”) ; 
nCountt++ ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
Des trove incon (hWnd) ; 
- break ; : 
} 
break ; 
case WM_DESTROY: 
Atom = GlobalFindAtom ("Test String") ; 
for (i =0; i < nCount ; i++) 
et oba [DeLerenton CAtom) ; 
PostQuitMessage (0) ; 
break ; 
default: ; 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
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GLOBALGETATOMNAME meWin2.0 mWin3.0 mWin31 

Purpose _ Retrieves a character string from the global atom table. 

Syntax WORD GlobalGetAtomName(ATOM nAtom, LPSTR lpBuffer, int nSize); 

Description Any application that has the nAtom value for an atom in the global atom table can determine the 
associated character string by calling this function. The character string is copied to the IpBuffer 
memory buffer. 

Uses _Used by applications that exchange character data. The nAtom value can be passed as the 
wParam value in a message sent between the two applications. 

Returns WORD, the number of bytes copied to the pBuffer memory buffer. Zero on error. 

See Also GlobalAddAtom()  — : 

Parameters 

nAtom ATOM: The atom value. This is the value returned by GlobalAddAtom(). 

lpBuffer LPSTR: A pointer to a memory buffer that will contain the character string. The buffer must be at 
least nSize bytes long. 

nSize int: The maximum number of characters to copy to lpBuffer. 

Example See the example under the GlobalAddAtom() function description. 

IntITATOMTABLE mWin2.0 mWin3.0 mWin3.1 

Purpose Initializes the local atom table. _ 

Syntax BOOL InitAtomTable(int nSize); 

Description Before the local atom table can be used, it must be initialized. InitAtomTable() allows the num- 
ber of top-level table entries to be specified. The default number (if nSize is set to NULL) is 37. 
This is adequate to efficiently store several hundred character strings. Larger values can be set if 
a large number of strings are to be stored in the local atom table. Note that the local atom table 
resides in the limited local memory area. Large amounts of data should be stored in the global 

- atom table. 

Uses This function must be called before the local atom table can be used. 

Returns BOOL. TRUE if the function was successful, FALSE on error. 

See Also AddAtom() 

Parameters Z 

nSize int: The number of top-level entries to set in the local atom table. This value should be a prime 
number. Set to NULL for the default number of 37 top-level entries. Larger values result in faster _ 

retrieval of strings, but require more memory space. : 

Example See the example under the AddAtom() and FindAtom() function descriptions. 
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Metafiles are coded GDI (Graphics Device Interface) function calls. The GDI functions are described in Chapter, 10, 
Device Contexts, Text Output, and Printing, and Chapter 11, Painting the Screen. When a metafile is “played,” the 
result is the same as if the GDI functions had been used directly. The difference is that metafiles can be stored in 
memory or as disk files, reloaded, and played any number of times by different applications. Metafiles are frequently 

the most compact means of storing graphical data. Most GDI functions require less than 16 bytes of data when en- _ 
coded in a metafile The exact number of bytes depends on the number of parameters the function uses. Compare 
metafiles to bitmaps. A 100 by 100 pixel bitmap with 16 colors requires 5,000 bytes of storage. Metafiles are also more 
device-independent than bitmaps, as the GDI functions are interpreted at run time, based on the output device con- 
text. 


Creating and Playing a Memory Metafile 


Metafiles are created by using GDI functions on a metafile device context. This is a special type of device context that 
only records the GDI function calls, not the results of the functions. If the GDI function calls are recorded in memory, 
the metafile is a “memory metafile.” 

To create a metafile that draws a rectangle filled with a hatched brush pattern, use the following code: 


static HANDLE hMetaFile ; 

HBRUSH hBrush ; 

HDC hMetaDC, hDC ; 

hMeWaDC = CreateMetaFile (NULL) ; . /* create memory metafile */ 
if ChMetaDC != NULL) 

{ 


hBrush = CreateHatchBrush (HS _DIAGCROSS;,’*RGB (0, O, 255)) ; 
SelectObject (hMetaDC, hBrush) ; 
Rectangle (hMetaDC, 0, 0, 100, 50) ; ; ; 
hMetaFile = CloseMetaFile chMetape) ; /* stop GDI input */ 
DeleteObject (hBrush) ; 
hDC = GetDC (hWnd) ; 
PlayMetaFile (hDC, hMetaFile) ; ,/* aieplay metafile to hoc */ 
ReleaseDC (hWnd, hoc) s 

} 


CreateMetaFile() creates the metafile device context. The GDI functions CreateHatchBrush(), SelectObject(), 
and Rectangle() are recorded into this device context. When all of the graphics functions have been recorded, the 
metafile device context is closed with CloseMetaFile(). 

CloseMetaFile() returns a handle to the memory metafile, which is a global memory area containing the encoded 
GDI function calls. PlayMetaFile() i is used to display this data to a physical device, such as the screen or printer. 
PlayMetaFile() sends each encoded function to the Windows GDI. The results appear just as if the GDI functions were 


being used directly. If you are going to use the metafile again, you will want to save the metafile handle as a static 
variable. 


Creating and Displaying a Disk Metafile | 
The GDI functions can be captured in a disk file just as easily as ina memory block. The advantage of using a disk file 
is that the metafile can be saved and played later without the time required to re-create all of the GDI function calls. 
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Here is the same example shown previously, but using a disk metafile: 


HANDLE ' hMetaFile ; 
HBRUSH hBrush ; 
HDC hMetaDC, hDOC ; 


hMetaDC = CreateMetaFile ("“mymeta.mf") ; /* create disk metafile */ 
if ChMetaDC != NULL) 


£ 
hBrush = CreateHatchBrush CHS_DIAGCROSS, RGB (0, 0, 255)) ; 
SelectObject (hMetaDC, hBrush) ; 
Rectangle (hMetabDC, 0, 0, 100, 50) ; 
CloseMetaFile (hMetaDC) ; 
DeleteObject (hBrush) ; 
} 
[Other program lines] ° 
hDC = GetDC ChWnd) ; 
hMetaFile = GetMetaFile ("mymeta.mf") ; /* load metafile */ 
PlayMetaFile C(hDC, hMetaFile) ; /* display it on hDC */ 


ReleaseDC (hWnd, hDC) ; 


In this example, a file name is passed to CreateMetaFile(). The encoded GDI calls go into this file, rather than 
into a memory area. Later in the program, the GetMetaFile() function is used to load the disk metafile into memory so 
that it can be played using PlayMetaFile(). 

There are two common uses for disk metafiles. One is as a compact method of storing graphics data for use.in a 
program. The metafiles are generated as the program is developed. The final program is distributed with the metafiles 
on the distribution disks. The program uses the metafile data, without having to generate the metafile each time the 
program is run. The second use for disk metafiles is as a means of storing graphics data for a painting or design 
application. Metafiles are ideal if the application uses objects like lines, rectangles, and ellipses for drawing. Metafiles 
are not useful if the paint program is pixel based, allowing arbitrary changes to any pixel. In this case, a DIB bitmap is 
the best option. Windows also uses metafiles internally when printing to a printer that only prints one band of pixels 
at a time (such as a dot matrix printer). The GDI outputs are stored in a metafile before printing begins. The metafile 
is played once for each band of printer output. A convenient way to keep track of metafiles used by a program is to add 
them to the .RC resource script file. The line 


mymeta METAFILE"“mymeta.mf" 


will include the MYMETA.MF disk metafile in the resource data. When it is time to play the metafile, the data can be 
recovered from the resource pool by using 


HANDLE - hMetaFile, hResource ; 
HDC HDC ; 


hResource = LoadResource (hInstance, FindResource (hInstance, "“mymeta", "METAFILE")) ; 
LockResource (hResource) ; : 

hMetaFile = SetMetaFileBits ChResource) ; 

GlobalUnlock (hResource) ; 


hOC = GetDC (hWnd) ; 


PlayMetaFile (hDC, hMetaFile) ; 
ReleaseDC (hWnd, hDC) ; 


SetMetaFileBits() returns a handle that can be passed to PlayMetaFile() to display the metafile data. 
Metafile Disk Format 


Normally, you will not have to be concerned with the data format used internally by metafiles. If you are curious, read 
on. Otherwise, skip to the next section. The disk file format for metafiles starts with a METAHEADER structure, 
defined in WINDOWS.H as follows: 
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typedef struct tagMETAHEADER 


{ 
WORD mtType; /* 1=memory, 2=disk filte*/ 
WORD mtHeaderSize; /* the size of this header */ 
WORD mtVersion; /* windows version number, 0x300 = ver 3.0 */ 
DWORD mtSize; /* size of the data */ 
WORD mtNoObjects; /* number of objects (brush, pen, eee) x/ 
DWORD mtMaxRecord; /* size of the largest record */ 
WORD mtNoParameters /* reserved */ 


} METAHEADER 
After the header, each GDI function is encoded in a METARECORD data structure. 
typedef struct tagMETARECORD 
{ 


DWORD rdSize; /* size of the record */ 
WORD rdFunction; /* the function id value */ . 
~ WORD rdParm(1); /* parameter data — may be more than one */ 
} METARECORD; 
typedef METARECORD *PMETARECORD; 
typedef METARECORD FAR *LPMETARECORD; 


The METARECORD structure is the same structure used to encode the metafile data in memory. The key element 
in this structure is rdFunction, the numeric ID value for the GDI function. The ID values are defined in WINDOWS.H, 
and they all start with the prefix “META_.” For example, the ID value for the LineTo() function is META_LINETO, 
which is defined as 0x0213. The parameter values follow the GDI function ID values. The number of parameter data 
words will depend on the parameters in the function. 


Altering the Metafile Image 


The simplest way to use a metafile is to just play back the GDI data without modification. The metafile will always be 
displayed in the same location and with the same dimensions, because the function parameters, such as a rectangle’s 
X and ¥ corner locations, are written directly into the metafile data. To move the location where a metafile is dis- | 
played, you must “trick” the metafile by changing the logical coordinate system. If a metafile is set to output starting 
at the 0,0 point, but the origin is moved to the center of the window’s client area, the metafile picture will be displayed 
in the center. The SetWindowOrg() function moves the logical origin of a device context. 

Metafiles can also be stretched and compressed during playback by changing the scale of the logical coordinate 
system. The SetMapMode(), SetWindowExt(), and SefViewportExt() functions allow complete flexibility as to the 
relative scaling. The example program under the CloseMetaFile() function description uses all of these techniques to 
display one metafile at two different locations, with two different sizes, and scale the images to fit the size of the 
window’s client area. : 

The ultimate way to modify a metafile is to intercept each GDI function call as the data is pulled from the metafile, 
and modify the data before it is displayed. The EnumMetaFile() and PlayMetaFileRecord() functions are provided for 
this purpose. To use EnumMetaFile() requires adding a callback function to your program. EnumMetaFile() calls this _ 
function once for each GDI call in the metafile. Within the callback function you can examine and change any of the 
coded metafile data, prior to displaying it with PlayMetaFileRecord(). The example program under the Enum 
MetaFile() function description uses this approach to change the pattern brush used to fill in regions. 


Metafile Limitations | . 
_Not every GDI function can be recorded to a metafile. The simplest way to check whether a function can be used is to 
see if the function name is defined with a metafile ID number in WINDOWS.H. This is not foolproof, 4s some GDI IDs 
apply to more than one function. Here are some general rules covering the functions that cannot be used in metafiles. 
1. Metafiles cannot return information about the environment because the metafile data exists independent of any 
real device. Functions such as pee pads Geeneedays”) and GetTextMetrics() will not work ina 
metafile. . 
_ 2. Metafiles cannot process bitmap data o or align brush patterns. Functions like GrayString(), Drawlcon(), and 
- SetBrushOrg() cannot be used. 
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8. The metafile device context does not refer a “real” device. Functions like CreateCompatibleDC(), ReleaseDC(), 
and DeleteDG@ should not be used in metafiles. 


4. The FillRect() and FrameRect() functions do not work in metafiles because they require handles to brushes. 


By design, metafiles do not have default values for pens, brushes, colors, etc. When a metafile is played, it simply 
executes the GDI function calls given the current status of the device context. This means that you may end up with 
different results depending on when a metafile is played. For example, a metafile that does not create a pen will draw 
with whatever pen color is in effect. 

The opposite problem occurs when a metafile changes the devices context settings for colors, coordinate system 
scaling, etc. There is no way for a metafile to determine the current settings in order to reset them to their previous 
state after use. Any changes made to the device context by the metafile will remain in effect after playback has 
stopped. 

There are several ways to handle the device context changes incurred with a metafile. The simplest is to create a 
new device context after the metafile is played. That way any changes the metafile makes to pens, brushes, etc. will be 
deleted when the old device context is destroyed. 

Amore sophisticated way of dealing with the device context changes is to store a copy of the device context before 
the metafile is played. SaveDC() does this. After the metafile has been played, RestoreDC() is used to recover the old 
device context settings. You should decide on a general philosophy of either having the metafile use the existing 
brushes and pens selected into a device context, or always having the metafile create its 0 own pens and brushes. The 
latter is the preferred approach. 


Metafile Function Summary 
Fable 23-1 summarizes the metafile functions. The detailed function descriptions are in the next section. 


CloseMetaFile Closes the metafile device context, and returns a handle that can be used to play the metafile. 


CopyMetaFite Copies a metafile to either a disk file or a memory metafile. 
CreateMetaFile "Creates a metafile device context, ready to receive GDI painting information. 
 DeleteMetaFile . Frees the system resources: associated with a metafile. . 
EnumMetaFile Plays a memory metafile back one GD! ‘unction at a time, allowing the GDI function parameters 
to be changed. 
GetMetaFile Loads a disk metafile into memory. 
GetMetaFileBits Returns a handle to the global memory block containing a memory metafile. 
PlayMetaFile Outputs a metafile to a device context. 
PlayMetaFileRecord Displays a single GDI function call to a device from within an enumeration Callback function for a 
: metafile. 


SetMetaFileBits Creates a memory metafie from data stored in a global memory block. 


Table 23-1. Metafile Function Summary. 


Metafile Function Descriptions 
This section contains detailed descriptions for the metafile functions. 


CLosEMETAFILE ; gWin2.0 mWin3.0 \m@Win3.l 


Purpose © Closes the metafile device context and returns a handle that can be used to play the metafile. 
Syntax — HANDLE CloseMetaFile(HANDLE hDC); 
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Description 


Uses 


Returns 
See Also 


Parameters 
hDC 


Example 


/ 


When painting operations to the metafile device context opened with CreateMetaFile() are com- 
pleted, the metafile must be closed for input. CloseMetaFile() returns a handle te-the-completed 
memory metafile. This handle is used to play the metafile using the PlayMetaFile() function. 


Used after the painting operations creating the metafile are complete. This function must be 
used before the metafile can be displayed. 


HANDLE, the metafile handle. Returns NULL on error. 


CreateMetaFile(), PlayMetaFile() es It! Quit. ea 


HDC: The metafile device context created with CreateMeta- 
File(). This device context is invalid after CloseMetaFile() is 
called. 


This example demonstrates creating and painting a metafile 
image. The metafile is created when the application processes 
the WM_CREATE message. WM_SIZE messages are inter- 
cepted to save the size of the client area. When a WM_PAINT message is received, the metafile is 
painted twice. The size of the image the metafile creates is changed by using the 
MM_ANISOTROPIC mapping mode, to change the logical device scaling. The second time the 
metafile is painted, the size is doubled, as the logical X¥ and Y extents are cut in half. If the user | 
clicks the “Do It!” menu item, the metafile is written to a disk file named “twoelips.mf.” The 
memory metafile is deleted as the application exits. 


"Figure 23-1. CloseMetaFile() 
Example. 


long FAR PASCAL WndProc €HWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


static HANDLE hMetaFile ;- 
HBRUSH hBrush ; 
HDC hMetaDC ; 
PAINTSTRUCT ps; 
static int xClient, yClient ; 
switch (iMessage) /* process windows messages */ 
{ : 
case WM_CREATE: , /* Buntd memory metafile */ 


hMetaDC = CreateMetaFile (NULL) ; . ms 
if ChMetaDC != NULL) 


{ ‘, 

hBrush = CreateHatchBrush (HS_DIAGCROSS, 
RGB (0, 0, 255)) ; 

SelectObject (hMetaDC, hBrush) ; 
Ellipse (hMetaDC, 0, 0, 100, 50) ; 
Ellipse (hMetaDC, 20, 0, 80, 120) ; 
hMetaFile = CloseMetaFile (hMetaDC) ; 
DeleteObject (hBrush) ; 

.} 

break ; 

case WM_SIZE: 

xClient = LOWORD (lParam) ; 

yClient = HIWORD (lParam) ; 

break ; 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
SetMapMode (ps.hdc, MM_ANISOTROPIC) ; 
SetWindowExt (ps.hdc, 300, 300) ; 
SetViewportExt (ps.hde, xClient, yClient) ; 
SetWindowOrg (ps.hdc, 0, 0) ; 
PlayMetaFile (ps.hdc, hMetaFile) ; 


SetWindowExt (ps.hdc, 150, 150) ; 
SetViewportExt (ps.hdc, Relient yClient) ; 
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SetWindowOrg (ps.hdc, -50, -25) ; 
PlayMetaFile (ps.hdc, hMetaFile) ; 
EndPaint (hWnd, &ps) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) . 
{ 
case IDM_DOIT: /* save the meta file to disk */ 
‘CopyMetaFile ChMetaFile, SENSEI RSH mf") ; 
break ; 


case IDM_QUIT: 
DestroyWindow ChWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 
DeleteMetaFile (hMetaFile) ; . 
PostQuitMessage (0) ; 


b k > 
default: “a /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, LParam) ; 
. : 
return (OL) ; 
} 
CopyMETAFILE mWin2.0 mwWin3.0 mWin31 
Purpose Copies a metafile to either a disk file or a memory metafile. 
Syntax — HANDLE CopyMetaFile(HANDLE hSrcMetaFile, LPSTR lpFileName); 
Description This function copies a metafile to a disk file. Disk metafiles are a compact means of storing 
graphical information. Alternatively, if the eM tte parameter is set to NULL, the source 
metafile is copied to a memory metafile. 
Uses Normally used to write memory metafile data to a disk file. 
Returns HANDLE, the handle of the new metafile created. 
See Also GetMetaFileQ) 
Parameters ; 
hSrcMetaFile HANDLE: The handle of the metafile to copy. This is the value returned by CloseMetaFile() or 
GetMetaFile(). 
lpFileName LPSTR: A pointer to a null-terminated character string containing the disk file name to create. If 
lpFileName is set to NULL, the source metafile is copied to a new memory metafile. 
Example See the previous example under the CloseMetaFile() function description. 
CrEATEMETAFILE . meWin2.0 eWin3.0 @Win3l 
- Purpose Creates a metafile device context, ready to receive GDI painting information. 
Syntax HDC CreateMetaFile(LPSTR lpFilename); ; 
Description This function creates a metafile device context. This is not the same as a device context opened 
° with GetDC() or CreateDC(). Metafile device contexts store GDI (Graphics Device Interface) 
function calls, so that they can be played back later. 
Uses This is the first step in creating a metafile. 
Returns HDC, a handle to the metafile device context created. 
See Also 


~ CloseMetaFile(), PlayMetaFile() 
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Parameters 

lpFilename LPSTR: A pointer to a null-terminated character string containing the name of the disk file that 
will receive the metafile data. Alternatively, lpFilename can be set to NULL, creating a memory 
metafile device context. 

Example See the example under the CloseMetaFile() function description. 

DELETEMETAFILE | mWin2.0 wWin30 mWin3.1 

Purpose Frees the system resources associated with a metafile. 

Syntax BOOL DeleteMetaFile(HANDLE hMF); 

Description | This function frees the system resources associated with a metafile. The metafile handle canbe — 
retrieved with GetMetaFile(). Disk metafiles are not deleted from disk by this function. 

Uses Used to free the system memory when the metafile is no longer needed by the application. 

Returns ‘ BOOL. TRUE if the system resources have been freed, FALSE on error. 

‘See Also CloseMetaFile(), GetMetaFile(), CopyMetaFile() : 

Parameters 

hMF HANDLE: The metafile handle. This is the value returned by CloseMetaFile() when the metafile 

was created, or by GetMetaFile() when a disk metafile was loaded. 

Example See the example under the CloseMetaFile() function description. 

ENuMMETAFILE | 3 mWin2.0 mWin3.0 mWin31 

Purpose Plays (enumerates) a memory metafile back one GDI function at a time, allowing the GDI func- 

# tion parameters to be changed. 

Syntax BOOL pumaetakilet De hDC, ee hMF, FARPROC lpCallbackFunc, BYTE FAR - 

| *lpClientData); 

Description Metafiles consist of a series of bia coded GDI (Graphics Device Interface) function calls. 
EnumMetaFile() calls a callback function once per GDI call. The callback function can examine 
the GDI data and modify it before using PlayMetaFileRecord() to display the GDI output. 

Uses" Modifying a metafile during playback (for example to change the colors, pens, or brush patterns 

used). 

Returns BOOL. TRUE if the function successfully Processed each GDI function call in the metafile. False 
on error. 

See Also PlayMetaFileRecord() _ 

’- Parameters 
hDC HDC: The device context handle passed to the callback function with each enumeration. 
hMF LOCALHANDLE: The handle of the memory metafile. This is the value returned by Close-— 
MetaFile() and/or GetMetaFile(). sc 
lpCallbackFunc FARPROC: The procedure-instance address of the callback function. This value is returned by 
MakeProclInstance(). The callback function must be listed in the EXPORTS section of the 
ne program's .DEF definition file, and it must have the format shown below. . 

lpClientData BYTE FAR *: A pointer to data to be passed to the callback function. This can be used to pass 
data, such as colors or pattern numbers, to the callback function. . 

Callback Function The callback function must be in the following format: 


int FAR PASCAL EnumFunc (HDC DC, LPHANDLETABLE ee LPMETARECORD ipMR, 
int nObj, BYTE FAR *lpClientData) ; 
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The callback function should return 1 to continue displaying the metafile, 0 to stop playback. 
The callback function parameters are defined as follows. 


hDC HDC: This is the device context handle for the device to receive the metafile output. This value is 
passed to the callback function by EnumMetaFile(). 
lpHTable LPHANDLETABLE: A far poner toa HANDLETABLE data structure. This is defined i in WIN- 
DOWS.H as follows: 


typedef struct tagHANDLETABLE 
{ 


HANDLE objectHandlef1]; /* can be more than one */ 
. } HANDLETABLE; 
‘typedef HANDLETABLE *PHANDLETABLE; 
typedef HANDLETABLE FAR *LPHANDLETABLE; 
lpMFR LPMETARECORD: A far pointer to a METARECORD data structure. This is defined in WIN- 
DOWS.H as follows: 
typedef struct tagMETARECORD 
{ f: 
DWORD rdSize; /* the size of this record */ 
WORD rdFunction; /* the GDI function number */ 
WORD rdParml1]; /* the parameter data */ 
} METARECORD; 
typedef METARECORD *PMETARECORD; 
typedef METARECORD FAR *LPMETARECORD; 


The rdSize element of this structure is convenient, as the size of each METARECORD entry 
depends on the number of bytes of parameter data used by the GDI function called. The number 
of rdParam{[] elements will depend on the number of parameters the GDI function calls. The 
function is identified with the rdFunction element. Metafile-compatible GDI functions are iden- 
tified in WINDOWS.H with ID values starting with “MF_.” . 


nObj int: The number of objects with handles stored in the HANDLE TABLE. 
lpClientData BYTE FAR *: The data passed to the callback function by EnumMetaFile(). 


Example As shown in Figure 28-2, this example displays the disk . 
: metafile TWOELIPS.MF when the user clicksthe“Do It” menu FRA eregatetg fv [+ 
item. During playback, the brush pattern used in the Create aoe 
HatchBrush() GDI function call is changed to the HS_CROSS Bolt! Quit 
style. Compare this figure with Figure 23-1 to see the differ- 
ences in the brush patterns. . 

The brush pattern is changed within the metafile enu- 
meration function EnumMF(), shown at the bottom of the list- 
ing. This function is called one time for every GDI call in the 

_ metafile. EnumMF() checks for the GDI function ID for Create 
HatchBrush(), and then modifies one of the parameter values 
before passing the data.to PlayMetaFileRecord(). Note that 
EnumMF() must be listed in the EXPORTS section of the : 
program’s .DEF definition file, and it must have afunction pro- Figure 23-2. Enum Meta- 


totype added to the program’s header file. File() Example.” 
Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 
static HANDLE hMetaFile ; 
HDC hDC ; 
FARPROC fpEnumFunc ; 
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Jf 


‘switch (iMessage) . ? ' . /* process windows messages */ 


_case WM_CREATE: /* Load metafile */ 
if(!ChMetaFile = GetMetaFile ("“twoelips.mf"))) 
MessageBox (hWnd, "Could not Load TWOELIPS.MF", 
"File Problem", MB_OK) ; 
break ; : 
-case WM_COMMAND: - /* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: 
hDC = GetDC ChWnd) ; 
fpEnumFunc = MakeProciInstance (EnumMF, ghInstance) ; 
EnumMetaFile (hDC, hMetaFile, fpEnumFunc, NULL) ; 
FreeProcInstance CfpEnumFunc) 7 
ReleaseDC (hind, hDdC) ; 


break ; 
case IDM_QUIT: [* send end of APPEL Eee on message */ 
_ DestroyWindow (hWnd) ; 
_ break ; 
} 
break ; 
case WM_DESTROY: /* stop application */ 


DeleteMetaFile (hMetaFile) ; 
PostQuitMessage (0) ; 
- break ; 
default: /* default windows message processing */ 
return De fWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 


int FAR PASCAL EnumMF CHDC hDC, LPHANDLETABLE LpHTable, 


LPMETARECORD LpMFR, int nObj, BYTE FAR *lpClientData) 


{ 
_ /* check for create hatch brush function == MF_CREATEBRUSHINDIRECT */ 
if CUpMFR->rdFunction == MF_CREATEBRUSHINDIRECT) 
{ 
LpMFR->rdParm £3] = HS_CROSS ; /* change brush pattern */ 
} 
PlayMetaFileRecord C(hDC, LpHTable, LpMFR, nObj) ; 
return (1) ; 
} ° 
GETMETAFILE | wWin2.0 mWin3.0 mWin3.1 
Purpose Loads a disk metafile into memory. 
Syntax HANDLE GetMetaFile(LPSTR ipFilename); ; 
Description This function reads a disk metafile into memory and returns a 
handle to the metafile. The handle can be used to display the 
metafile using PlayMetaFile(). 
Uses Disk metafiles are a compact way to store graphics data cre- 
ated with GDI function calls. They require much less space | 
than storing the bitmapped image. ; 
Returns HANDLE, the metafile handle. Returns NULL on error, such as 
- not finding the disk file. 
See Also PlayMetaFile(), CopyMetaFile(), CreateMetaFile() 


Figure 23-3. GetMetaFile() - 
Example. 
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Parameters _ : 

lpFilename LPSTR: A pointer to a null-terminated string containing the DOS file name of the disk metafile. 
: This can be an extended file name, including the full directory name. 

Example This example, which is shown in Figure 23-3, displays the disk metafile “twoelips.mf.”. See the 


CloseMetaFile() function description for an example program that creates the disk metafile. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ . 


static HANDLE hMetaFile = NULL ; 
PAINTSTRUCT ps >; 
HANDLE ; hMem ; 
char ° cBuf £1282 ; 
HOC hdc ; 
int nSize ; 
switch (CiMessage) , /* process windows messages */ 
{ 
case WM_CREATE: /* Load metafile */ 


if('! ChMetaFile = GetMetaFile (“twoelips.mf"))) 
MessageBox (hWnd, “Could not load TWOELIPS.MF", 
“File Problem", MB_OK) ; 

break ; 
case WM_PAINT: 

BeginPaint (hWnd, &ps) ; 

if (hMetaFile) 

PlayMetaFile (ps.hdc, hMetaFile) ; 

EndPaint ChWnd, &ps) ; 

break ; 
case WM_COMMAND: 

switch (wParam) 

cg 

case IDM_QUIT: 

DestroyWindow (hWnd) ; 
break ; 

} 

break ; 
case WM_DESTROY: 

DeleteMetaFile ChMetaFile) ; 

PostQuitMessage (0) ° 


break ; 
default: 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
} 
GeTMETAFILEBITS Win2.0 e@Win3.0 mWin3. 
Purpose. Returns a handle to the global memory block containing a memory metafile. 
Syntax HANDLE GetMetaFileBits(HANDLE hMF); 

- Description This function returns a handle to a global memory block containing a metafile. The metafile data 
consists of binary-coded GDI function calls. This data should not be modified. The AMF handle to 
the metafile is invalid after GetMetaFileBits() returns. SetMetaFileBits() can be used to restore 
the metafile handle. 

Uses Applications can manipulate the global memory block using the normal memory management 


functions. This is typically done in order to copy more than one memory metafile into a file or 
data structure used by a graphics program. 
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Returns 
See Also 


Parameters | 
hMF 


Example 


HANDLE, the global memory handle for the metafile data. —— 
NULL on error. = generic. [~ [= 
SetMetaFileBits() is used to restore the metafile handle after Dolt! Quit 


_ GetMetaFileBits() has been called... . Re 
: . : OY 2, 4 
. XD, 
Pe SER 
HANDLE: The memory metafile handle. This is the value re- Reece 
turned by CloseMetaFile() and/or GetMetaFile(). PNR 


This example creates and paints a metafile. When the user 
clicks the “Do It!” menu item, the program obtains a global [Metafile size = 128 bytes. 
memory handle to the memory block containing the memory 
metafile. The GlobalSize() function is used to determine the Figure 23-4. GetMeta- 

size of the memory block. The metafile requires 128 bytes of FileBits() Example. 

storage, which is remarkably compact. For comparison, 128 

bytes would store only 32 pixels of a bitmap with a 16-color bitmap. The graphics portion of Figure 
23-4 contains 13,000 pixels, or 6,500 bytes if stored as a bitmap. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


static HANDLE hMetaFile = NULL; 

HBRUSH : hBrush ; 

HDC hMetaDC ; 

int nSize ; 

PAINTSTRUCT ps ; 

HDC hoc ; 

HANDLE hMem ; 

char cBuf £128] ; 

switch (iMessage) /* process windows messages */ 
{ 


case WM_CREATE: /* build metafile */ 
hMetaDC = CreateMetaFile (NULL) ; 
if ChMetaDC $= NULL) 


{ 
hBrush = CreateHatchBrush CHS_DIAGCROSS, 
RGB (0, 0, 255)) ; 
SelectObject (hMetaDC, hBrush) ; 
Rectangle (hMetaDC, 0, 0, 100, 30) ; 
Pie (hMetaDdC, 0, 30, 100, 100, 100, 100, 0, 100) ; 
MoveTo (hMetaDCc, 0, 100) ; é 
_LineTo (hMetabdc, 100, 100) ; 
hMetaFile = CloseMetaFile (hMetaDC) ; = 
DeleteObject (hBrush) ; , 
} 
break ; 


case WM_PAINT: 

BeginPaint (hwnd, - &ps) ; 

if (hMetaFile) 

PlayMetaFile (ps.hdc, hMetaFile) ; 

EndPaint (hWnd, &ps) ; 

break ; -_ 
case WM_ COMMAND: ; . ¢*® process menu items */ 

' switch (wParam) 
{ 


case IDM_DOIT: 
hDC = GetDC (hwnd) ; 
hMem = GetMetarileBits chnecsr tre? 3 
nSize = GlobalSize (hMem) ; 
hMetaFile = setmacarilepits ChMem) a 
TextOut (hdc, 0, 120, cBuf, wsprintf (cBuf, 
“Metafile size = %d bytes.", nSize)) ; 
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ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
; DestroyWindow (hWnd) ; 
break ; 
} 
break ; 


case WM_DESTROY: /* stop application */ 


DeleteMetaFile chet akttey ay 
Pos tauithessage (0) ; 


break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, (Param) ; 
} 
return (OL) ; 
} 
PLAYMETAFILE : mWin2.0 mWin3.0 mWin3.1 
Purpose Outputs a metafile to a device context. 
Syntax BOOL PlayMetaFile(HDC hDC, HANDLE hMF); 
Description This function runs the metafile in order to display the graphics output. The metafile GDI (Graph- 
ics Device Interface) function calls are played to the ADC device context. The size and location of 
the output can be changed by sehus different device context scalings and origin locations for 
. hDC. 
Uses Displaying a metafile on a device. 
Returns BOOL. TRUE if the function was successful, FALSE on error. 
See Also CreateMetaFile(), CloseMetaFile, SetWindowExt(), SetWindowOrg() 
_ Parameters . 
hDC HDC: The device context handle for the device that will receive the metafile output. 
hMF HANDLE: The handle of the metafile to play. This is the value returned ed CloseMetaFile() or 
GetMetaFile(). 
Example See the example under the CloseMetaFile() function description. 
PLavYMeraFeRecorp , mWin2.0 mWin3.0 mWin3.1 
Purpose ‘ Displays a single GDI function call to a device from within an enumeration callback function for 
a metafile. 
Syntax void PlayMetaFileRecord(HDC 2DC, LPHANDLETABLE UpHandletable, LPMETARECORD 
lpMetaRecord, WORD nHandles); . 
Description . EnumMetaFile() calls a callback function once per GDI function in the metafile. Within the call- 
back function, PlayMetaFileRecord() is used to output the single GDI call to the device. The GDI 
parameter data can be modified before this function is called. 
Uses - Used within the callback function when using EnumMetaFile() to modify a metafile Sung play- 
: back. 
Returns No returned value (void). 
See Also EnumMetaFile 0 
Parameters . , 
hDC HDC: The device context handle for the device to receive the GDI OuMnUE This is the HDC passed 


to the callback function by EnumMetaFile(). 
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lpHandletable LPHANDLETABLE: A far pointer to a HANDLETABLE data strucvure, defined in WINDOWS.H as 
‘ follows: 


typedef struct tagHANDLETABLE 
{ 


HANDLE objectHandleL[1]; ; /* can be more than one */ 


+ HANDLETABLE; 
typedef HANDLETABLE *PHANDLETABLE; ; 9 
typedef HANDLETABLE FAR *LPHANDLETABLE;. : 


lpMetaRecord LPMETARECORD: A far pointer to a METARECORD data structure, defined in WINDOWS.H as 
follows: 


typedef struct tagMETARECORD 
a 


DWORD rdSize; . : /* the size of this record */ 


“WORD : rdFunction; /* the GDI function number */ 
WORD rdParm[1]; /* the parameters */ 

} METARECORD; 
typedef METARECORD *PMETARECORD; a 
typedef METARECORD FAR *LPMETARECORD; , 

‘ . ; : ; . F- : ° Pat ke : 
nHandles WORD: The number of handles in the HANDLETABLE. This value is passed to the callback func- 

tion as the nObj parameter. - 

Example See the example under the EnumMetaFile() function description. 
SETMETAFILEBITS | m@Win2.0 wWin30 m@Win3.l 
Purpose . Creates a memory metafile from data stored in a global memory block. . ve 
Syntax . HANDLE SetMetaFileBits(HANDLE hMem); ¥ aa 
Description GetMetaFileBits() is used to obtain a handle to a memory metafile’ s alobal n memory block. After 


it is called, SetMetaFileBits() should be used to restore the metafile handle. SetMetaFileBits() 
returns a valid metafile handle that can be used for PlayMetaFile(). 


Uses. ; Used to convert a block of resource data into a memory metafile that can be played using 
’  PlayMetaFile(). 
Returns HANDLE, a memory metafile handle that can be pipaseet to PlayMetaFile(). 
See Also GetMetaFileBits() 
Parameters 
hMem HANDLE: The memory handle of the global memory block containing the metafile. This handle is 
returned by GetMetaFileBits() or LoadResource(). 


Example — See the example under the GetMetaFileBits() function description. Also see the discussion of 
loading a metafile as resource data at the beginning of this chapter. . 
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Windows includes the useful ability to set timers. Once set, a timer sends WM_TIMER messages to an application at 
preset intervals. These messages continue until the timer is shut off. Timers are used more frequently in Windows 
applications than in programs running in a conventional environment, such as MS-DOS. A DOS program can just loop 
forever, waiting for some event to occur. This situation would not work under Windows, as the application would take 
over the system and not allow other applications to run. Timers are a convenient way to periodically initiate some 
action, without having the application hog the environment. 


Using Timers 
Windows allows a maximum of 16 timers to be active at once. Each timer has a separate ID value, so that an applica-. 
_ tion can use more than one timer. The timers use the system clock, which limits the minimum time between timer 
events to 55 milliseconds. Longer time periods, up to about 596 hours, are possible. 

The SetTimer() function starts a timer. There are two ways to use this function. The most common way is to call 
SetTimer() with the fourth parameter set to NULL. 


static int nTimer ; 


if C!iCnTimer = SetTimer ChWnd, 1, 1000, NULL))) 
MessageBox (hWnd, “No Timers Left!", "Message", 
MB_OK) ; 

In this case, the timer will send WM_TIMER messages to the program’s WndProc() function every 1,000 millisec- 
onds (once per second). The timer’s ID value is returned by SetTimer(). The ID is an integer value that will be passed 
as the wParam value when the WM_TIMER message is received. If more than one timer is set, the timers will have 
different ID values, so they can be kept apart. Note that the SetTimer() return value is checked to see if it is zero. A 
zero value means that all 16 timers are being used. This is possible, so be sure to check this value before proceeding. 

The other way to call SetTimer() is to pass a procedure-instance address of a callback function to the function. 
The callback function receives the WM_TIMER messages, not the WndProc() function. A typical program fragment 
for this usage is 


static int nTimer ; 


fpTimerFunc = MakeProcInstance (TimerFunction, ghInstance) ; 
if (!(nTimer = SetTimer (hWnd, 1, 15000, fpTimerFunc))) 
MessageBox cnghd, “No timers left!", "Message", 
MB_OK) ; 
‘The callback function must follow a specific format, and it must be listed in the EXPORTS section of the program S 
.DEF definition file. See the SetTimer() function description for a complete example. 
The WM_TIMER messages will continue until the timer is shut down with the KillTimer() mncnor 


KillTimer (hWnd, nTimer) ; 


Timer Accuracy — 


Although timers can be set to: a frequency of one every 55 milliseconds, the intoevat batween dace events will not be 
that accurate. This i inaccuracy is because the WM_ TIMER messages are placed‘on the application’s message queue. 


Sf geht Se 4: 
| 
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Windows will only place the WM_TIMER message on the queue if the queue is empty (empty of all messages except 
WM_PAINT). Windows will not. put more than one WM_TIMER Message on the queue. This keeps the queue from 
filling up with WM_TIMER messages if a very short time interval is set. 

For most applications, exact precision between WM_TIMER messages is not necessary because the applications 
are not significantly affected if the WM_TIMER message is a bit late. For applications that require greater accuracy, 
other techniques are required. Applications like music recording/playback and some process control programs re- 
quire more accurate time keeping. This is generally done by using hardware interrupts, processed by a small program 
function and data buffer in a page locked memory block. The Windows program can periodically read and write to the 
memory buffer, leaving the exact timing of Pecipmlssonecep Hon to the interrupt driven routine. 


Other Time Functions 


Windows keeps track of the number of milliseconds since the system was started. This period of time is called “Win- 
dows time.” The millisecond count is a DWORD value that can be retrieved using GetCurrentTime() or GetTick 
‘Count(). Every Windows message is tagged with a time value. You can determine this value by either examining the 
contents of the MSG data structure in the program’s message loop, or by calling the GetMessageTime() pnenion 
within the body of the program. 

Windows does not provide a way to determine the outside world date and time from the system clock. The C 
compiler run-time library functions time() and ctime() can be used to fetch the current date/time and convert it toa 
character sting. 


Timer Function Summary 
Table 24-1 summarizes the Windows timer functions. The detailed function deSeHDHON are in the next section. 


Function 25 

GetCurrentTime Betis tf number of milliseconds since the system was booted. 
GetTickCount Returns the number of milliseconds since the system was booted. 
KillTimer Stops a timer. 

SetTimer Starts a Windows timer. 


Table 24-1. Timer Function Summary. 


Function Descriptions 
This section contains the detailed description of Windows time functions. 


GETCURRENTIIME sits | or | wWin2.0: @Win3d.0 mWin3l 
Purpose Returns the number of milliseconds since the system was booted... ~ * ee 
Syntax DWORD GetCurrentTime(void); 


Description Windows keeps an internal clock that starts when the system is booted. Each message is tagged 
with the clock count when the message is sent (GetMessageTime() retrieves this value). 
GetCurrentTime() returns the current clock count. The maximum accuracy is about 1/18th of a 


second. 
Uses Used to determine how long a message has been waiting in the message queue. The difference - 
between GetCurrentTime() and GetMessageTime() is the delay. 
Returns -  DWORD, the internal clock count in milliseconds. . 
See Also GetTickCount() 
Parameters None (void). 
Example | This example, which i is illustrated in Figure 24-1, sets a one second timer when the user clicks the 


“Do It!” menu item. When a WM_TIME message is received, both the message time and Windows 
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current clock value are retrieved. The difference between the two is the length of time the 
WM_TIME message waited on the application’s message queue. Because the WM_TIME mes- 
* gages are sent only if Windows passes control to the application, there will be no time delays if the 
application is sharing the Windows 
environment with other Windows 
applications. However, if Windows is 
running DOS applications concur- 
rently in 386 enhanced mode, delays 


Dott! Quit 
ick Count = 14024494, delay = 0, Max Delay = 1263 


will be registered by this program. Figure 24-1. GetCurrentTime() Example, 
Long FAR PASCAL WndProc CHWND hiind, ‘unsigned iMessage, WORD wParam, LONG lParam) 


DWORD . dwtickCount,) duMlessageTine, eepereys ; 

static OWORD dwMaxDelay = 0 ; 

char . cBuf £128] ; 

HDC hoc ; 

static int nTimer ; 

switch CiMessage) /* process windows messages */ 
§ 


case WM_TIMER: 
'  hdC = Getoc Chiind) ; 
SetBkMode (hDC, OPAQUE) ; 
duTickCount = GetCurrentTime () ; 
dwMessageTime = GetMessageTime () ; 
dwDelay = dwlickCount - dwMessageTime ; 
if (dwDelay > dwMaxDelay) 
dwMaxDelay = dwDelay ; 
TextOut Choc, 0, 0, cBuf, usprintf (cBuf, 
“Tick Count = Zlu, delay = %lu, Max Delay = Z%lu “, 
dwTickCount, dubelay, semenversy 2 7 
-Reteasede Chund, hDC) ; 
. or ae 
case ce conan Ds -  /* process menu items */ 
switch (wParam) 


case TDM DOIT: \ 
Ff C!CnTimer = SetTimer (hwnd, 1, 1000, NULL) )) 
MessageBox (hWnd, "No Timers Left!", "Message", 
MB_OK) ; 
_ break ; 
‘case IDM Quit: 
; DestroyWindow Chitnd) ; 
om break ; 
} 
‘break ; 
case wM_DESTROY: : /* stop application */ 
KillLTimer (hWnd, nTimer) ; 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing a] 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 


} 
return COL) ; | 


} Par 
GerTickCount <a mm Win2.0) @Win3.0 @Win 3.1 
Purpose — Returns the number of milliseconds since the system was booted. - 

Syntax . DWORD GetTickCount(void); 

Description = This function is identical to GetCurrentTime(). . 
Returns: _ DWORD, the number of milliseconds since the system was booted. 

SeeAlso -—>- Get CurrentTime(). : 
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Parameters None (void). 


Example Th pens ennpl can modedto we Cet nae Caren wt 
| . ho change in the operation of the program. — are 
Kas Tocge 2: Be eee ag se = ewin20 ‘emo30 . Win 3.1 
Syntax ee BOOL KiltTimer(HWND Aled, int nJDEvent); | ee 
Beserigtion ~~ Timers are created with SetTimer(). Once set, the timer will coritinue to generate WM. TIMER 
~ messages until the KillTimer() function is used to stop the timer’s execution. Any pending _ 
WM_TIMER messages are removed from the message queue when KilfTimer() is executed. = 
tes Shutting down a Windows timer. Tele een ae eee 
. _ beused by ancther application. = . 
Retares BOOL. TRUE if the timer was removed, FALSE on error. 
hWnd HWND: The handle of the window that owns the timer. — 
nlDEvent int: The ID ale of th tine to ll This the vale retured by Set 
Related Messages WM_TIMER 
Example See the examples under the SetTimer() and a faneton deacons, 
SerTimmer : 7 ao @Win20 @Win 30 owns 
Parpese ‘Starts a Windows timer. 
Symaan WORD SetTimer(HWND hWnd, int nDEvert, WORD wElapse, PARPROC ipfisiareas’: 


Description ‘This function starts a timer. If ipTimerFunc is set to NULL, the timer sents WM_TIMER mes- 

gages to the application at the wElapse interval. Iflp7imerFunc is a procedure-instance address 
of a callback function, the WM _TIMER messages are sent directly to that function, bypassing the 
normal WndProc() message processing. 

Because the timer messages are placed on the application's message quewe, they will not be 
received at the exact interval specified by wElapse, but they may be delayed by other Windows 
activities. A maximum of 16 timers are available to all applications running on the system. The 
application should check the returned value from SetTimer() to verify that a timer was availabie. 
Any time a periodic interruption is required within a Windows application. 

WORD, the integer ID of the timer. Tha value spared to Kilner) to remo the tine. Re- 
cee ene ee ne eee, . 


HWND: The handle of the window that will receive the WM_TIMER messages, 
int: The number of the timer. This value will be passed with the WM_TIMER message asthe 
Parem value. Timer ID values allow more than one timer to be set withia an application, and 
their WM_TIMER messages to be distinguished. | : 
wElapse WORD: The number of milliseconds between timer events. The minimum Ue betwoen events 
_ -gbout 65 milliseconds. — 


ipTimerFunc FARPROC: This is bot to NULL ifthe application will receive the WM. THMMRB saessagos direéty 
to the WndProc() function. To send the WM_TIMER messages to a separate callback function, 


Uses 
Returns 
See Also 
Parameters 
hWnd 
nlDBvent 
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set ipTimerFunc to the procedure instance address of the calthack function. This is the value 
returned by MakeProcInstance(). 


Caliback Function The timer callback functior. must be in the following form: . 
WORD FAR PASCAL TimerFunc (HWND AWnd, WORD wMsg, int nIDEvent, DWORD oe : 


hind HWND: The window handle of the window owning tho timer. 

wifsg WORD: Always WM_TIMER. 

nlDEvent int: The ID number of the timer. Thisis the returned value set when the SetTimer() function was 
called. 

dwTime - DWORD: The Windows clock value when the callback function is first called. This value is not 


updated as the callback function is repeatedly called. 
Related Messages: WM_TIMER peels pec leee fea 
Example | This example, which is illustrated in Figure 24-2, sets a timer 
that calls a callback function directly, rather than issuing 
‘WM_TIMER messages. The callback function displays the num- : cane 
ber of milliseconds since the system was started. The callhack Figure 24-2. SetTimer() 
function TimerFunction() must be listed in the EXPORTS sec- Example. 
tion of the program's .DEF definition, and a function prototype 
should be included in the header file. Note that the callback function cannot use the dw7ime 
parameter to show the system time. dw7¥me is only valid the first time the callback function is 
called. (See the example under GetCurrentTime( for an — of setting a timer without a . 
callback function.) 


tong F FAR PASCAL ndProc CHWND hind, unsigned iMessage, WORD uParan, LONG tParaa) 
FARPROC fpTimerfunc ; 


static iat nTimer ; 
ore (iflessage) /* process vindous messages &/ 
case WA_TINER: 
break ; ’ 
case WA, COMMAND: /* process menu itens */ 


switch CuParam) 
{ 


case I0M_DOIT: 
fpTimerFunc = RakeProcinstance (TimerFunctton, 


— ghInstance) ; 
tf Ci€nTimer = SetTiner Chund, 1, 1000, 
: fpTiaerFunc))> : 
Message Box Chiind, “No t es tefe!”, “Message”, 


BOK) ; 
break 2 oe 
case IDM_QUIT: ~ 
: ‘DestroyWindow Chind) ; 
break ; Sey : & 
: re 


break ; 

case WA_DESTROY: /* stop application ef 

; Kilt tiner Chund, nTimer) ; 

FfreeProciInstance (fpTimerFunc) ; 

Postaui ttessage (0) 5 ‘ 

break ; ee mares: 
default: /* default windows message processing */ 

a return DetuindowProc chends iMessage wParaa, (Parse) 3 


y 


— 


) 
feturn (OL) 3 . oO 


: ‘WORD FAR PASCAL TimerFunction CHUND hind, WORD ullsg, int nloTiner, pworo duT tee) 
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HOC) DG 
char cBuf £128) ; 
DWORD = dwCurrentTime ; 


dwCurrentTime = GetCurrentTime () ; 

hDC = GetDC (hWnd); - : 

SetBkMode (hDC, OPAQUE) ; 

TextOut (hDdC, 0, 0, cBuf, wsprintf (cBuf, : 
“System Up Zlu msec.", dwCurrentTime)) ; 

ReleaseDC (hWnd, hDC) ; ; = 3 : 
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Every example program in this book uses resources. The .RC resource script file of the GENERIC application includes 
the menu definition and program icon data. Other examples of defining dialog boxes, keyboard accelerators, and 
menus have been discussed in their respective chapters. Resources are frequently the most convenient way to store 
raw data needed by the program. Combining the static data needed by the application in the resource file avoids 
having a number of separate files that the application reads when needed. Resources are also efficient because they 
are usually loaded into memory only when needed. 


The Resource Compiler 


The NMAKE file for the GENERIC application includes two calls to the resource compiler RC.EXE (shown here with 
debugging options set on). 


ALL: generic.exe 


CFLAGS=-c -D LINT_ARGS -2i —Od -Gsw -W2 
LFLAGS=/NOD /co 


generic.obj : generic.c generic.h 
$(CC) SCCFLAGS) generic.c 


generic.res: generic.rc generic.ico paragraf.txt 
re -r generic.rc 


generic.exe : generic.obj generic.def generic.res 
Link SCLFLAGS) generic, , ,libw slibcew, generic 
re generic.res 


The first call to RC has the “-r” switch. This switch just compiles the resource file GENERIC.RC, producing an 
output file GENERIC.RES. The second call to the RC at the bottom of the listing does not have the “-r” switch. This call 
adds the compiled resource data to the executable program, creating the finished ready-to-run program. It also marks 
the program with the Windows version data, even if the program does not have resource data. The version data is 
detected when Windows version 3.0 or higher starts a program. If an earlier version of Windows is detected, a warning 
message is put on the screen. 

Both the resource compilation and final program assembly can be done with one call to RC. Just drop the first call 
to RC, and eliminate the “.res” after the resource name on the last line. Combining them this way is not recommended 
because the compilation is slow relative to final assembly. If there have been no changes to the resource data, there is 
no reason to recompile the resources every time the program is compiled and linked. There are some other compiler 
switches that you may find useful. They are listed in Table 25-1. ” 


oa Meaning 


-R Compile only. Creates a .RES file from a .RC file. 


-D Defines a symbol. This allows conditional compilation of the resource file if you use compiler 
directives, such as #ifdef in the .RC file (explained later). 

-FO Renames the output .RES file. The character string following this switch will be the output file 
name. 
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Table 25-1. continued | < 


FE S ne the EXE fle The characte string foloing th this snitch will be the BER f = name. 
| i "+ += Specifies a directory to search for include files. 
Vo Verbose compiler messages. . | : 
-X 7 2.3 Prevents searching of directories in the DOS PATH environment variable when the resource 
. compiler is looking for include files. 
-L or -LIM382 Use Lotus/Intel/Microsoft Expanded Memory Specification (EMS). 
-M or -MULTINST Assigns each program instance to a sees EMS bank only if the ENS 4.0 money: 
_ Configuration is active). if 
-E "Changes the global memory location for a DLL to above the EMS bank line. 
-P : Creates a private DLL (dynamic link library) that i is only accessible to one application. 
-K ; Disables load optimization of PRELOAD resources. By default all PRELOAD resource data is 
grouped together so that it can be loaded quickly. 
T Creates an application that will not run in Window's real mode. 
-2 or -H Displays help information on the resource compiler. | 


Table 25-1. Resource Compiler Switches. 
You can combine more than one letter option after an initial dash. For example 
RC -T -K -R generic.rc 
is equivalent to 
RC -TKR generic.rc 


Capital and lowercase letters are equivalent. 


The Resource Script File 28 . 
All of the resources used by the program are defined in the resource script file. Here is a typical example. 


/* generic.rc */ 
Hinclude <windows.h> 
#include "generic.h" 


generic “ICON generic.ico 
generic MENU 
BEGIN 
MENUITEM "“&Do It!" IDM_DOIT 
.MENUITEM “&Quit", IDM_QUIT 
END 


This resource script file includes an icon file in the data and defines the program’s menu. = 

There are four single-line resource script statements: BITMAP, CURSOR, FONT, and ICON. Each of these state- 
ments loads a data file of the specified type into the resource data. Once included in the resource data, the 
LoadBitmap(), LoadCursor(), and LoadIcon() functions are provided for direct access to the respective data within a 
program. AddFontResource() is the normal means of adding font data for use by all applications. There are five 
multiple-line resource script statements: ACCELERATORS, DIALOG, MENU, RCDATA, and STRINGTABLE. The first 
three are explained in Chapters 7, 13, and 4, respectively. The RCDATA and STRINGTABLE statements are described 
later in this chapter. 

The resource compiler recognizes a number of directives that can ihe used to control compilation. The most. 
common one is #include, which allows other files to be included into the resource file during compilation. The header 
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file atid any dialog box definition: files (created by the dialog box editor) are tically added to the resource file ‘tig 
#include lines. 

- Different parts of the resource file cut be compiled by using conditional compilation directives. They are #elif 
(else if), #else, #endif, #if, #ifdef, #ifndef, and #undef. These switches are usually used to allow the same resource file 
to compile both debug and non-debug versions. For example, the a resource file in the format 
Hifdef DEBUG . 

Cdebug program lines] 
_felse 


Cnon-debug program Lines] 
#endif 


would only compile the first group of program lines if the variable DEBUG was defined. It could be defined at the top 
of the resource script file with the #define directive, or defined in the command line for RC using the -D switch. 


tc -r -d DEBUG generic.rc 


Using the command line switch is a better approach, as it means that the debugging options can be controlled 
entirely from the program’ 's NMAKE file. 


String Tables 


Most programs use a series-of-character strings in “messages and character outputs. The conventional programming 
practice is to code the character strings right into the program as static data. Windows provides an alternative, called ' 
astring table. In this case, the character strings are defined in the resource data and are given an ID value. Here isan 
example. 


STRINGTABLE . 
BEGIN 
S_TITLE “Caption From .RC" 
; S_STRING “String Loaded From .RC” 
EN 


Each string is eren an ID value, which is usually defined in a separate header file. 
je generic. h */ 


fidetine SITITLE - 16 /* string table ID values */ 
Wdefine S_STRING 17 


When the application siede to use the data, the LoadString() function copies the character data from the re- 
. source file into a memory buffer. 


thar. gszTitte C32] ; 
char gszString [64] ; 


Loadstring (ghInstance, S_TITLE, gszlitle, sizeof (gszTitle)) ; 
LoadString ; (ghInstance, S_STRING, gszString, sizeof (gszString)) ; 


Strings in a string table can contain control characters like tabs and line feeds. They must be encoded as octal 
constants preceded by a backslash character 0. The octal value is the ASCII code for the control character. Here is : 
an example. . 


. STRINGTABLE : 
BEGIN : 
BODYTEXT “This text contains a \011tab,\012\015and a CR/LF pair" 


There are a number of advantages to using string tables. The main one is the reduction in memory use. The strings 
are not loaded until they are needed. Windows,loads strings into memory in blocks of up to 16 strings, based on the 
string ID numbers. Strings 0-15 are loaded in one call to LoadString(), 16-31 as another block, etc. Strings that are 
likely to be used ee are best — within a group of 16 integers. _ 
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By default, strings are loaded into memory that is both moveable and discardable. If the memory containing the 
string has been discarded, the next call to LoadString() will reload it from the disk data. The memory status for the 
strings in a string table can be set to either PRELOAD or LOADONCALL. The default is LOADONCALL, which means 
that the strings are not loaded into memory until LoadString() i is as ree ee loads’ the strings into memory 
when the program first starts. 

The string table can also be set to have the memory block FIXED, MOVEABLE, or Disc snpanle: The least 
desirable combinations of options would be a table listed as 
STRINGTABLE PRELOAD FIXED 
BEGIN 

/* strings here * 
END 

You can defeat the whole purpose of using string tables if the string data ends up copied into a static memory 
buffer. This means that the buffer will take up space, even if the character data has not been loaded into it from the 
string table, Most applications load the strings into automatic variables, which are temporarily stored on the stack 
and then discarded. 

Another reason to put strings into string tables is for future editing. For example, if the program is marketed in 
several countries, the resource file can be translated into another language without changing the source code. Be- 
cause the resource file also contains the menu and dialog box definitions, translating the resource file ends up com- 
pletely transforming the program into a new language with a minimum of fuss. 


Custom Resources 


Resource files are also an excellent place to put other types of static data, which can be anything from metafiles to raw 
binary data. The brute force way to include data is with an RCDATA statement in the resource script file. Here! is an 
example. 


DataID RCDATA PRELOAD MOVEABLE 


BEGIN 

3 

78 

0X444, 

"a string\0" 
END 


Like all resource data types, the RCDATA is given an ID number. The same memory options mentioned under 
string tables are available for RCDATA. In this case, the data will be preloaded, but not fixed in memory, and not 
discarded. The data consists of four integers and a character string. 

Usually, the best place to store the custom resource data is in an external file during program development. The 
file’s contents are then added to the resource data when the resource file is comme’: A Wpical set a CUSYONLRS re- 


sources is shown here.. 
paragraph TEXT “paragraf.txt" 
twoelips METAFILE “twoelips.mf"” 


These lines define the custom resource types “TEXT” and “METAFILE.” The data for these two resources is in two 
separate files, PARAGRAF.TXT and TWOELIPS.MF. The resource compiler reads in the two files and puts the data 
right into the resource file for the program. Within the body of the program, it is necessary to locate the start of the 
resource data before the data can be loaded into memory. FindResource() locates the resource data in the resource 
file, and LoadResource() loads it into a memory block. These are epicaly called together. 


‘~ 


HANDLE hMFRes - 


hMFRes = LoadResource (ghInstance, FindResource (ghInstance, "paragraph", "TEXT")) ; 


This example shows the location and loading of the TEXT data. The hMF Res returned value is a handle to the 
global memory block containing the loaded resource data. See the example under the Punalltesourcet) function de- 
scription for a more complete program listing. 
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Resource Function Summary 


oy “Uae pia? 
8 hye Nee 
Scenery 


AccessResource 


Table 25-2 summarizes the resource functions. The detailed function descriptions are in the next section. 


fs Prowt Srbeteli een i. TP ee rete Ae: ae 


Retums a file handle to data in the resource file. 


AllocResource Allocates global memory to hold a resource. 
FindResource Locates a resource in the resource file. 
FreeResource Removes a resource from memory. 
GetinstanceData Copies data from a previous instance of the same program into a memory buffer. 
LoadResource Loads a resource into memory. 
LoadString Loads a string from the resource file string table into a buffer. 
LockResource Locks a global memory block containing a resource. 
SetResourceHandier Creates a custom resource loading function, called by LoadResource{). 
SizeofResource Determines the size of a resource. 
Table 25-2. Resource Function Summary. is 


Resource Function Descriptions 
This section contains the detailed descriptions of resource functions. 


ACCESSRESOURCE . wWin2.0 mWin3.0 mWin3.1 


Purpose Returns a DOS file handle to data in the resource file. 
Syntax int AccessResource(HANDLE hinstance, HANDLE hResInfo), . 
Description This function opens the resource file data and moves the file pointer to the beginning of the data 
specified by hResInfo. The file handle can be used with the standard file functions, such as 
_lread(), and should be closed after use with _Iclose(). The file cannot be written to. DOS file 
handles are a limited resource. Be sure to release the file handle when done by calling _Iclose(). 
Uses Can be used to allow selective reading of portions of a resource item. To load the entire resource, 
use LoadResource() | 
. Returns int, a DOS file handle. Returns —1 on error. . . =.» generic {-fe 
See Also AllocResource(), SizeofResource() , WEE Apraqaorlad hall 
Parameters : . e displayed in the window’s client 
hinstance HANDLE: The instance handle of the application which has ae 
the resource file. This value can be retrieved with GetWindow- [a CRLEpair. 
Word(). . -. Figure 25-1, Access 
hResInfo HANDLE: A handle to the specific data item in the resource  Resource() Example. 
file. Use FindResource() to obtain this value. , 
Example This example loads and displays a custom resource. In this case, the resource data is just a block 
, of text saved in an ASCII file. The text is displayed in the window's client area when the user 
clicks the “Do It!” menu item, as shown in Figure 25-1. 
Note This example demonstrates several seldom used resource functions. Considerably simpler meth- 


ods are available for loading resources. See the example under the FindResource() function de- 
scription for a more typical example. | 

The resource file defines the custom resource type “TEXT” as being loaded from the file 
PARAGRAF. TXT. . hoe 
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/*-generic.rc */ 

#include <windows.h> 

#include “generic.h" : ‘ PoBse 

generic : ICGN generic.ico - >e fe a2 
generic MENU se th 8h fins 
BEGIN , é . ; . 
MENUITEM "&Do It!" . IDM_DOIT 

MENUITEM “&Quit", IDM_QUIT 

' END : : 

paragraph TEXT paragraf.txt 


The PARAGRAF-TXT file was created with a text processor. 


This is a paragraph of text that will 

be displayed in the window's client . ; 

area. The text is stored in an ASCII % a i ae 
text file. Each end of a line oe ; \ 

a CR/LF pair. ae 


The custom resource is located in the resource data using FindResource(). AllocResource() 
allocates a global memory block to hold the data. ee provides a file handle to the 
data, so that it can be loaded into memory using . Iread(). . 


long FAR PASCAL WndProc (HWND hWnd, unsigned iMessage, WORD secraa,,wawe tbaegey..” : 
{ 


HDC hDdC ; 
HANDLE hText >! 
static HANDLE hMem ; 
WORD wResSize 7 
int i, nResFile ; 
LPSTR LpResDdata ; 
‘static RECT rClient ; 
switch message) ee ‘/* process windows messages */ 
{ oS 


case WM_ CREATE: 
hText = FindResource (ghInstance, “paragraph”, “TEXT") ; 
wResSize = SizeofResource (ghInstance, hText) ; 
hMem = AllocResource (ghinstance, hText, 7 
CDWORD) wResSize) ; 
lpResData.= GlobaLlLock. ChMem) ; 
nResFile = AccessResource (ahine vanes: htext) ; . 
‘if (nResFile $!=-1)  ——.. : 
{ ba oy 


_lread enneer Aree i dalek he wRessize) ; 
} : vit 
GlobalUnlock Chien) 3 
_lclose (nResFile) ; 
break ; 
case WM_SIZE: 
SetRect (&rClient, 0, 0, LOWORD (lParam), HIWORD ClParam)) ; 
break ; 
case WM_ COMMAND: /* process menu items ef 
switch (wParam) mt 
{ 
case IDM_DOIT: 
hDC = GetDC (hWnd) ; 
tpResData = GlobalLock (hMem) ; 
DrawText ‘(ChDC, LpResData, (strlen CtpResbata, 
- &rClient, DT_EXPANDTABS) ; 
GlobalUnlock (hMem) ; © 
Reteasedt ChWind, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow chiind) ; 
break ; 


break ; 
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case WH_DESTROY: 
Globalfree (hMem) ; 
eee ee (0) 
break ; 
default: Sp 
return DefWindowProc Chiind, iMessage, wParam, lParam) ; 


} 
return COL) ; 


} ts 
ALLOCRESOURCE eae mWin2.0 mWin3.0 mWin3.1 
Parpose ' _Allocates global memory to holda: a resource. 

Syntax HANDLE DLE hinstance, HANDLE hResInfo, DWORD dwSize); 

Description . This function-returns a ha a handle to a global memory block. The function will compute the size of 

eg ae ang ‘the block to allocate if the dwSize parameter is set to NULL. 

Uses . AllocResource() i is called internally by Windows to process LoadResource() function calls, It is 

. _ hot normally used by itself. 

Returns HANDLE, a handle toa global memory block. 

See Also . AccessResouree(), SizeofResource() 

hinstance HANDLE: The instance handle of the program containing the resource data. This value can be 
retrieved with GetWindowWord(). : - 

hResInfo HANDLE: The handle of the specific resource that will be loaded into memory. Use 
FindResource() to determine this value. 

dwSize DWORD: The number of bytes to allocate. If this value is set to NULL, the minimum size that will : 
hold the resource data will be allocated. , 

Example See the example under the AccesaResource() function description. 

a : ge Win2.0 mm Win3.0 mi Win3.1 

Purpese Locates a resource in the resource file. 

Syntax HANDLE FindResource(HANDLE hinstance, LPSTR ipName, LPSTR lpType); | 

Description Before a resource can be loaded into memory for use, it must be located. FindResource() returns ‘ 
a handle to the resource in the resource file. 

Uses Used in conjunction with LoadResource() to load resources into memory for use. 

Returns HANDLE, the handle of the resource in the resource file. NULL if the resource cannot be located. _ 
This handle is not the memory handle of a loaded resource. Use LoadResource() to return a 
memory handle. 

See Also LoadResource() 

Ainstance - HANDLE: The program’s instance handle. This value can be retrieved by calling GetWindow- 

Word(). . 
lpName LPSTR: A pointer toa null-terminated character string containing the name oft the resource. This 
’ isthe name specified on the left side of the resource definition line in the RC resource script file. 
lpType LPSTR: A pointer to a null-terminated character string containing the resource type. For custom 


resources, this is the string specified in the second field of the resource definition line in the .RC 
resource script file. For predefined resource types, the [pType parameter should be set equal to 
one of the values in Table 25-3. 
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RT. ACCELERATOR Accelerator table. 


RT_BITMAP Bitmap. 

RT_DIALOG Dialog box template. 
RT_FONT Font. 

RT_FONTDIR Font directory. 
RT_MENU Menu definition. 
RT_RCDATA User-defined resource. 


Table 25-8. Predefined Resource Types. 


leary 


Example ‘ This example, which is shown in Figure 25-2, loads and dis- 
. plays two custom resources, a metafile’ and a block of ASCII 
text. 

The program's resource sorip file includes two ‘eistonh re- comes pa la 
source types, “TEXT” and “METAFILE.” They used to include aren. The teas 
the data in the two referenced files into the application’ sre- _ stored in an ASCIil 
source data. - ftext file. Each end of a line has 


a CRILF pair. 
' Figure 25-2. FindResource() 


/* generic.rc */ ; 
’ #include <windows.h> © 


#Hinclude "generic.h" Example. 
generic ICON generic.ico : : . a 
generic MENU 
BEGIN . oie 
MENUITEM "“&Do It!" ; IDM_DOIT 
MENUITEM "&Quit", I0M_QUIT 
END . 
paragraph TEXT “paragraf.txt" 
twoelips METAFILE “twoelips.mf" 


The text file PARAGRAF.TXT was cereale with a text editor. The first six lines are tabbed, to 
make room for a metafile picture. 


This is a paragraph . 
of text that will 
be displayed in the 
window's client 
area. The text is 
; stored in an ASCII 
text file. Each end of a line has 
a CR/LF pair.\ 


The application loads the resource data when the WM_CREATE message is processed. 

SetMetaFileBits() is used to return a handle to the metafile that can be passed later to 

“yc PlayMetaFile(). The length of the character string resource Is determined by searching for the 
backslash character (\). 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, sige tec eaes 


PAINTSTRUCT ps; - 

static RECT ' pCltent ; 
Static HANDLE . hTextRes, hMetaFile ; 
static . int nTextLong ; 
LPSTR ows lpChar se 
HANDLE 4 : “hMFRes ; = er ca 
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switch (iMessage) F /* process windows messages */ 
t a 
case WM_CREATE: 
hMFRes = LoadResource (ghInstance, 
FindResource (ghInstance, "“twoelips", 
“METAFILE")) ; 
LockResource ChMFRes) ; 
hMetaFile = SetMetaFileBits ChMFRes) ; 
GlobalUnlock ChMFRes) ; 
hTextRes = LoadResource (ghInstance, 
FindResource (ghinstance, "paragraph", "“TEXT")) ; 
UpChar = LockResource (hTextRes) ; 
nTextLong = 0 ; : 
while (*lpChart+ != "\NV') /* find text Length */ 


nTextLongtt ; /* "\" at end */ 
“GlobalUnlock (hTextRes) ; 
break ; 


case WM_SIZE: 
SetRect (&rClient, 0, 0, LOWORD (lParam), HIWORD (lParam)) ; 
break ; 
case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
LpChar = LockResource (hTextRes) ; 
DrawText (ps.hdc, lLpChar, nTextLong, &rClient, 
DT_EXPANDTABS) ; 
GlobalUnlock (hTextRes) ; 
PlayMetaFile (ps.hdc, hMetaFile) ; 
EndPaint (hWnd, &ps) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
t 
case IDM_DOIT: /* "Do it" menu item does nothing */ 
break ; 
case IOM_QUIT: /* send end of application message */ 
DestroyWindow (hWnd) ; 
break ; 
bea bigs 
’ break ; OE pegee 
case WH DESTROY: oa: i stop appLicanion */ 


FreeResource phheranrle2-; 
FreeResource (hTextRes) ; 
PostQuitMessage (0) ; 


break ; 
default: © , . /* default windows message processing x] 
“" "return DefwindowProc (hWnd, iMessage, wParam, lParam) ; 

} 

return (OL) ; 
} 7 

“oo Bs 
FREERESOURCE mWin20 mWin30 mWin31 
Purpose _ Removes a resource from memory. 
Syntax BOOL FreeResource(HANDLE hResData); 
| Description Ifa resource is loaded more than once, Windows does not load two copies of the data. Instead, the 


reference count of the resource is increased by one for each time LoadResource() is called. 
FreeResource() decreases the reference count by one. When the reference count reaches zero, 
the resource is deleted. Note that the resource data is freed when the program terminates. It is 
not necessary to call FreeResource() for every resource loaded. Normally, FreeResource() is used 
within a program to reduce memory consumption for resources that are unlikely to be reused. 


Uses Because of the use of a reference count for each resource, different parts of the same application 
can both load and delete the same resource without concern about interfering with other uses of 
the sta in the ee 
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Returns . BOOL. Zero if the function was successful, non-zero on error. Note that this is the oppasite of the 


normal TRUE/FALSE assignment. 
See Also LoadResource(), FindResource(). _ : a 
Parameters . 3 
hResData HANDLE: The resource handle returned by LoadResource(). 
~ Example See the example under the FindResource() function description. ~ 
GerINstanceDATA 3 | mWin2.0 mWin30 mWin31 
Purpose ' Copies data from a previous instarice of the same program into a memory buffer. 
Syntax __ int GetInstanceData(HANDLE hinstance, NPSTR pData, int nCount); ~~ 
Description If more than one copy of a program is .run at the same time, éach copy shares the same code 


‘segments, but separate copies of data segments are maintained: GetInstanceData() allows data 

_ to be copied from a previous instance of the program into a subsequent instance’s data segment. 
The data is copied in the order that it occurs in the first instance’s data segment. Repeated calls 
to GetInstanceData() read successive blocks of data, each nCount bytes long. 


Uses Used with programs that are likely to have multiple instances loaded, such as terminal emulator 
_ programs that allow several sessions to be run at the same time. ae from a een 
stance is faster than reloading the data from disk. 


Returns int, the number of bytes copied. See ne Tele 
. = Caption from BO Pe tse 
See Also | LoadResource(), LoadString() 
pre | sa , 
hinstance _ HANDLE: The instance handle of the previous instance of the 
_ - application. This is available as the hPrevInstance parameter Figure 25-3. GetInstance- 
passed to the WinMain() function. ' Data() Example. 
 pData NPSTR: A pointer to a memory block in the application's own 
pote Sg _ data segment. 
“= .mCount .-- ~_- int: The number of bytes to copy. = 
Pag Example Zot - + ..‘This example loads two strings from a resource file. One is used for the window's captive: The 


other is displayed in the client area if the “Do It!” menu item is clicked, as shown in Figure 25-3. 
The program’s .RC resource file includes two strings in a string table. 


/* generic.rc */ 

include <windows.h> 

include “generic.h" 

generic ICON generic.ico 


generic MENU 
BEGIN : 
MENUITEM “&Do It!" IDM_OOIT. 
MENULTEM "SQuit", IOM_QUIT 
En” 3 : 
STRINGTABLE 
BEGIN 
S_TITLE “Caption From .RC"- 
S_STRING “String Loaded From .RC" 


END ; aos | | z et, in, 
| The ID values for the strings are defined in the program’s header file. 


/* generic.h = */ e348 
#define IDM_DOIT1 /* menu item id values */ 
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#define IDM_QUIT2 


#define S_TITLE 16 /* string table ID values */ 
H#define S_STRING 17 
/* global variables */ 
int ghIinstance ; 
char gszAppName [] = "generic" ; 


/* function prototypes */ OS 
Long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 


The first time the program is run, the two strings are loaded into memory with LoadString(). 
If the program is started a second or subsequent time, the first instance of the program uses the 
GetInstanceData() function within WinMain() to copy the two strings inta Hobal character buff- 
ers from the resource data. 


/* generic.c generic windows application */ 


#include <windows.h> 
#Hinclude “generic.h" 


char gszTitle [32] ; 
«Ghar. gsz8tring C64] ; 


int PASCAL WinMain CHANDLE hInstance, HANDLE hPrevInstance, LPSTR LpszCmdLine, int nCmdShow) 


HWND “hWnd ; 

MSG msg ; 

WNDCLASS wndclass ; 7 : 
ghInstan'ce = hInstance ; /* store instance handle as global var. */ 
if ('hPrevinstance) 

{ 


LoadString (ghInstance, S_TITLE, gszTitle, 
sizeof (gszTitle)) ; 

LoadString (ghInstance, S_STRING, gszString, 
sizeof (gszString)) ; 


wndclass.style CS_HREDRAW | CS_VREDRAW ; - 


wndclass.LpfnWndProc WndProc ; 
wndclass.cbCtsExtra 0; 
wndclass.cbWndExtra 0; 


wndctass.hInstance 
wndclass.hIcon 
wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.lpszClassName 


hinstance ; 

Loadicon (hInstance, gszAppName) ; 
LoadCursor (NULL, IDC_ARROW) ; 
GetStockObject (WHITE BRUSH) ; 
gszAppName ; 

gszAppName ; 


Te et rt | | 


if C!RegisterClass (&wndclass) ) 
return FALSE ; 


}. 
else 
{ is 
GetInstanceData (hPreviInstance, gszTitle, 
sizeof (gszTitle)) ; 
GetInstanceData (hPreviInstance, gszString, 
sizeof (gszString)) ; 
} 
hWnd = CreateWindow ( ; _./* create the program's window here */ 
gszAppName, ./* class name */ 
gszTitle, : /* window name */ 
WS_OVERLAPPEDWINDOW, /* window style */ 
CW_USEDEFAULT, /* x position on screen */ 
_ CWLUSEDEFAULT, - /* y position on screen */ ~~. 
’ CW_USEDEFAULT, /* width of window */ = 
CW_USEDEFAULT,. - /* height of window */ 
NULL, — /* parent window handle (null = none) */ 
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NULL, /* menu handle (null = use class menu) */ 
hInstance, /* instance handte */- 
NULL) >; - /* Lpstr Cnull = not used) */ 


ShowWindow ChWnd, nCmdShow) ; 
UpdateWindow ChWnd) ; 7 


{ 


} 


while (GetMessage (&msg, NULL, 0, 0)) /* the message loop */ 


TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 


return msg.wParam ; 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


HDC hdc ; 
switch (iMessage) /* process windows messages */ 
‘ case WM_COMMAND: /* process menu items */ 
switch (wParam) 
an IDM_DOIT: /* User hit the “Do it" menu item */ 


hDC = GetDC (hWnd) ; 
TextOut ChDC, 0, 0, gszString, lstrlen (gszString)) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 


break ; 
} e 
break ; 
case WM_DESTROY: /* stop application */ 
PostQuitMessage (0) ; 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
} 
LoaDRESOURCE BWin2.0 m8 Win3.0 Win 3.1 
Purpose Loads a resource into memory. . 
Syntax HANDLE LoadResource(HANDLE hJnstance, HANDLE hResInfo); 
Description Resource data must be loaded into memory before it can be used. If LoadResource() is called 
more than once for the same resource, the data is not loaded multiple times. Instead, Windows 
keeps track of the number of times LoadResource() was called for the given resource as the . 
| “reference count” of the resource. The resource is not removed from memory until Free Re- 
source() has been called an equal number of times, or the application is terminated. 

The application can provide a custom resource loading callback function that will be called 
when the LoadResource() function is called. Use SetResourceHandler() to set the callback 
function. 

Uses Used with FindResource() to load resources into memory so that they can be used. 

Returns HANDLE, the handle to the global memory block that contains the loaded resource. Returns 
NULL if the resource could not be loaded. © 

See Also FindResource(), FreeResource(), SetResourceHandler() 

Parameters o 

hInstance HANDLE: The instance handle of the running program. This value can be retrieved by cabins 


GetWindowWord(). 
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i : a * at ad 


hResInfo 


Example 


LOADSTRING 


Purpose 
‘Syntax 
“Description 


~ Uses... 


Returns ~ 
See Also _ 
Parameters 
hInstance 


wiD 


lpBuffer 


nBufferMax 
Example 


/* generic.rc */ 


HANDLE: The handle of the resource within the resource data. This value is obtained by calling 
FindResource(). 


See the example under the FindResource() function description. 


Sop 
f 


Jf 


w Win 2.0 Win 3.1 


Loads a string from the resource file string table into a buffer. 

int LoadString(HANDLE hJnstance, WORD wID, LPSTR [pBuffer, int nBufferMax); 

Strings are added to the program’s resource file in a string table. Each string is given an ID value, 
normally defined in the program’s header file. LoadString() copies the string from the resource 
file into a buffer so that it can be manipulated and displayed. To be memory efficient, the (pBuffer 
should either be an automatic variable (stored on the program’s stack), a temporary memory 
block allocated by the program, or a static buffer that can be reused as different strings are 


f@ Win 3.0 


- loaded. Loading string resources into a series of static buffers is inefficient and defeats the pur- 


pose of using resource files to minimize memory consumption. 


The best place to store string constants is in resource files. This niethiad of stoate is memory 
efficient, and it makes edits or translations of the strings much simpler. 


int, the number of characters copied to the buffer. Returns zero on error. 


LoadResource() 


HANDLE: The instance handle for the program. 


WORD: The ID value for the string in the string 
table. This is the value to the left of the string in 
the resource file. Normally, it is given a defined 
name in the program’s header file. 


LPSPR; A pointer to a memory buffer to hold 
the character string. The buffer must be atleast 
nBufferMax characters long. 


his text Fantains a- 
and a CRILF pair 


igi 25- 4, Loads renal ) Beanie 


» int: The maximum number of characters to copy to the lpBuffer memory buffer. 


“This example, which is illustrated in Figure 25-4, includes three character strings in the resource 


file string-table. One string is displayed inthe window’s client area each time a WM_PAINT 
message is received. The other two strings are used in message box functions. 

The strings are defined in the program’s resource file. Note the octal constants used to code 
the tab, CR, and LF characters in the first text line. 


Hinclude <windows.h> 
Hinclude "generic.h" 


generic 


generic 
BEGIN 


END 


STRINGTABLE 


BEGIN 


ICON generic.ico 


ene 
MENUITEM "2D0 Ie" 
MENUITEM "SQuit", 


IDM_DOIT 
IDM_QUIT 
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BODYTEXT. "This text contains a \011tab,\012\015and a CR/LF sgl 
MESSAGE1 "This is message 1" 
MESSAGE2 "This is message 2" 


END 


The ID values for the strings are defined in the program’s header file. 


/* generic.h */ 


#define IDM_DOIT 1 /* menu item id values */ 

#define IDM_QUIT 2051 

Hdefine BODYTEXT : 0 /* number 0 - in first segment */ 

#define MESSAGE1 .16- : - f*® numbers 16 & 17 will be loaded */ 

Hdefine MESSAGE2 17 /* into a different segment together */ 
/* global variables */ 

int ghInstance ; ° /* these two globals are required */ 


char gszAppName CJ = “generic” ; . /* if you include winmain.c */ 
/* function prototypes */ _ 
Long FAR PASCAL WndProc CHWND, unsigned, WORD, LONG) ; 


.The program uses the BODYTEXT rng when 1 processing WM PAINT “Messages, The. other... 
“two strings are used in message boxes.» ae 


long FAR PASCAL WndProc. CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ y 


PAINTSTRUCT ps ; : 

static RECT rClient ; 

char cBuf (128) ; 

switch (iMessage) . . ee /* process windows messages */ 
{ : mae te : biG 


case WM_SIZE: 
Perret Carclient, 0, 0, LOWORD (lParam), HIWORD (LParam)) ; 
’ break ; 
case WM_PAINT: 
BeginPaint (hWnd, ae 
LoadString (ghinstance, BODYTEXT, cBuf, 128) ; 
DrawText (ps.hdc, cBuf, Saerten (cBuf), ercticne. 
DT_EXPANDTABS) ; 
EndPaint ChWnd, &ps) ; 
break ; - 
case WM_COMMAND: /* process menu items */ 
switch (wParam) : 
{ 
case IDM_DOIT: 
LoadString (ghInstance, MESSAGE1, cBuf, 128) ; 
MessageBox (hWnd, cBuf, "Message", MB_OK) _ 
break ; 
case IDM_QUIT: 
LoadString (ghInstance, MESSAGE2, cBuf, 128) ; 
MessageBox (hWnd, cBuf, "Message", MB_OK) ; 
DestroyWindow (hWnd) ; 
break ; 
} 
break ; 
case WM_DESTROY: 
PostQuitMessage (0) ; 
break ; 
default: 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} : ; 
return (OL) ; 
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LockRESOURCE mWin2.0 mWin30 mf Win3.l 

Purpose _ Locks a global memory block containing a resource. 

Syntax LPSTR LockResource(HANDLE hResDaia). 

Description This function locks a resource in global memory and returns a far pointer to the memory block’s 
address. If the resource is locked more than once with LockResource(), an equal number of 
FreeResource() function calls will be needed before the memory block is freed. 

Uses This is a convenient way to ey lock resource data loaded into memory by Load Re- 
source(). 

Returns LPSTR, a pointer to the beginning of the memory block containing the resource data. NULL on 
error. 

See Also LoadResource(), FindResource() 

Parameters 

hResData* HANDLE: The handle of the loaded resource data in memory, returned by LoadResource(). 

Example See the example under the FindResource() function description. 

SETRESOURCEHANDLER 7 mWin20 mWin3.0 mWin3. 

Purpose - Creates a custom resource loading function, called by LoadResource(). 

Syntax FARPROC SetResourceHandler(HANDLE hinstance, LPSTR ipType, FARPROC l[pLoadFunc); 

' Description This function allows you to define a custom resource loading function that will be called by 
LoadResource(). This is convenient if you will need to examine or modify the resource data dur- 
ing the loading process. . 

Uses Not often used. Can be used with custom resource types, where the data in the resource file needs 
to-be reformatted in memory. For example, appending a null character to the end of character 
data once it is loaded in memory. 

Returns “FARPROC, a pointer to the callback function. 

See Also LoadResource(), FindResource(), AccessResource() 

Parameters’ 

hInstance‘ HANDLE: The instance handle of the program containing the resource data. You can use Get- 
WindowWord() to retrieve this value. 

lpType LPSTR: A pointer to a null-terminated character string containing the resource type. This is the 
second field in the resource script file line that defines the resource. . 

lpLoadFunc FARPROC: The procedure-instance address of the loader function. This value is returned by 

, MakeProclnstance(). 

Callback Function The callback function must have the following format, and be listed in the EXPORTS section of 
the program’s .DEF definition file: 
FARPROC FAR PASCAL LoadFune (HANDLE hMem, HANDLE hinstance, HANDLE hResInfo) 

hMem HANDLE: A handle to the global memory block that will contain the resource data. If this value 
is NULL, the callback function should allocate a global memory block big enough to hold the 
resource. The SizeofResource() function will return the minimum size to allocate.) 

hInstance HANDLE: The instance-handle of the program containing the resource data. 

hResInfo HANDLE: The handle of the resource in the resource data file. This value is obtained by Find- 


Resource()and passed to the callback function when the LoadResource() function is called. 


oo 869 


WINDOWS API BIBLE 


The callback function should return the memory handle of the global memory block contain- 
ing the loaded resource data. IfhMem is not NULL, but an attempt to lock the memory block fails, 
the block has been discarded. In this case, the callback function should reallocate and reload the 
resource data. 


Example _ This example fieimousivares the use of a custom resource loading function. The loader 
LoadStringRes() is shown at the bottom of the listing. It must also be included in the EXPORTS | 
section of the program’s .DEF definition file, and a function prototype must be added to the 
header file. In this case, a custom resource type TEXT is defined in the resource file. This in- 
cludes a text file PARAGRAF.TXT in the resource data. 


/* generic.rc */ 
#include <windows.h> 
H#include “generic.h" 


generic ICON generic.ico 

generic MENU 

BEGIN ¢ 
MENUITEM "&Do Iti" IDM_DOIT 
MENUITEM “SOuit", IDM_QUIT 

END 

paragraph TEXT paragraf.txt 


The custom resource loader for the TEXT resource type is set by SetResourceHandler(). Once ~ 
set, the loader function is called when LoadResource() is used to load this resource type into 
memory. The callback function returns a handle to the loaded resource data in a global memory 
block. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ : 


HDC , hDC ; 

HANDLE hText ; 

static : HANDLE hMem ; 

LPSTR LpResData ; \ 

static RECT rClient ; ; 

FARPROC ‘ fpLoaderiInst ; 

switch CiMessage) /* process windows messages */ 
{ 


case WM_CREATE: 
-hText = FindResource (ghInstance, "paragraph", "TEXT") ; 
fpLoaderInst = MakeProcInstance ((FARPROC) LoadStringRes, 

'  ghiInstance) ; 

SetResourceHandler (ghInstance, "TEXT", fpLoaderInst) ; 
hMem = LoadResource (ghInstance, hText) ; 
break ; 

case WM_SIZE: 
pet hect (&rclient,- 0, 0, LOWORD (LParam), HIWORD (LParam)) ; 
break ; . 

case WM_ COMMAND: /* process menu items */_ 
switch (wParam) 


case IDM_DOIT: /* display the resource text */ 
hDC = GetDC ChWnd) ; 
lpResData = LockResource (hMem) ; 
DrawText ChDC, LpResData, Peerien RtpRestatays 
&rClient, oT EXPANDTABS) ; 
GlobalUnlock (hMem) ; 
ReleaseDC (hWnd, hDed 7 
break ; 
case IDM_QUIT: 
DestroyWindow (hWnd) ; 
wy break ; 
} : 
break ; 
- case WM_DESTROY: 
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PostQuitMessage (0) ; 
break ; 
default: 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (COL) ; 


FARPROC FAR PASCAL LoadStringRes (HANDLE hMem, HANDLE hInstance, HANDLE hResInfo) 
{ 

pint wResSize, nResFile ; 

LPSTR lpResData ; 


if (hMem == NULL) 
hMem = AllocResource ChInstance, hResInfo, (DWORD) wResSize) ; 
wResSize = SizeofResource (ghInstance, hResInfo) ; 
LpResData = GlobalLock (hMem) ; 
nResFile = AccessResource ChInstance, hResInfo) ; 
if (nResFile != -1) 
{ 


_lread (nResFile, LpResData, wResSize) ; 
_lclose (nResFile) ; 

} 

GlobalUnlock (hMem) ; 

return (CFARPROC) (DWORD) hMem) ; 


} 

S1ZEOFRESOURCE mWin2.0 m8 Win3.0 mWin3l 
Purpose Determines the size of a resource. 

Syntax WORD SizeofResource(HANDLE hinstance, HANDLE hResInjfo); 

Description This function returns the minimum size that a resource will occupy when loaded into memory. 
Uses Used with AllocResource() and AccessResource() to size and resource data into a memory area. 
Returns WORD, the size of the resource in bytes. Returns zero on error. 

See Also AccessResource(), AllocResource() 

Parameters 

hInstance HANDLE: The program’s instance handle. The value can be retrieved with GetWindowWord(). 
“hResInfo HANDLE: The resource handle of the specific item in the resource file to size. This value is 

returned by FindResource(). 
Example See the example under the AccessResource() function description. 
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A new addition to the Software Development Kit (SDK) for Windows 3.0 is the execution profiler. This tool allows you 
to track which parts of an application are taking the most time. Armed with this knowledge, you can work on speeding 
up the slowest parts of the program to get the maximum improvement for programming time spent. 

The CodeView for Windows debugger is a critical element of the SDK. Besides allowing debugging of Windows 
programs, the debugger is an excellent way to learn how Windows programs work. Armed with a two-monitor system 
(VGA and monochrome display on the same computer), the programmer can watch the source code execute line-by- 
line on the monochrome monitor while seeing the Windows application's progress on the VGA screen. (The Windows 
3.1 debugger allows debugging with only one monitor, or two VGA screens.) This chapter documents a few functions 
that can be used to “hard code” debugging information into the program during development. 


How the Profiler Works 


The basic idea behind a profiler is simple. When the profiler is on, the program is interrupted at some fixed frequency. 
Every time the program is interrupted, the profiler checks and stores the name of the part of the program that was 
executing at that moment. Over time, the parts of the program that are taking the most time tend to get the most 
“hits.” They tend to be the parts of the program that are operating when the interruption occurs. After the program is 
stopped, the statistics from the profiler are summed and analyzed to determine which parts of the program are taking. 
the most time. 

The Windows profiler works on this principle. The profiler stores the hit data in a memory buffer. When the 
profiler is stopped, or the ProfFlush() function is called, the memory buffer is written to a disk file. A DOS application 
called SHOWHITS.EXE then summarizes the statistics and outputs the data to the screen. This chain of actions to use 
the profiler is shown in Figure 26-1. 

The profiler reduces the performance of the application being run. The amount of degradation will depend on 
how often the program is interrupted. Typically, the reduction in performance is not noticeable. . 


Preparing to Run the Profiler 
Assuming that you are running Windows in the 386 en- 
hanced memory mode, the profiler is a Windows device a 
driver. You install the profiler by adding the VPROD.386 as 
driver to the [886Enh] portion of the SYSTEM.INI file 
and restarting Windows. 


C386EnhI 


DEVICE=VPROD. 386 
The SDK also includes support for profiling applica- - Be ae ull — 

tions in the Windows “real” memory mode by running the Se Ae 

PROF.COM program before Windows is started. Because paren a a 


commercial realities demand that all Windows programs 
be able to run in standard and 386 enhanced modes, this ELIS ER RT IES ae 
option is of little value. . . Figure 26-1. Windows Execution Profiler. 
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The program that will be profiled must be modified slightly to control the profiler. The sample rate and sample 
buffer size are set at the beginning of the program using the ProfSampRate() and ProfSetup() functions. 


ProfSampRate (1, 2) ; /* two milliseconds sample interval*/ 
ProfSetup (100, 0) ; /* 100 kbyte buffer in memory */ 
ProfClear () ; /* empty buffer to start*/ 


Specific parts of the program are marked for profiling by surrounding the code with ProfStart() and ProfStop() 
function calls. The profiler will be active from the point of execution marked with ProfStart() to the point marked 
with ProfStop(). The range of program lines profiled includes all functions called between ProfStart() and ProfStop() 
(including Windows functions), and any other parts of the program that may be executed as Windows processes other 
messages in the time period between these two markers. 


ProfStart () ; 
[Program lines to profile] 
ProfStop () ; i 

Any number of ProfStart() and ProfStop() pairs can be placed in tne program, isolating sections that will be 
profiled. At the end of the program, the ProfFinishQ) function should be called to write the profile memory buffer data 
to disk. The data is written to the CS1PS.DAT file on the WINDOWS subdirectory. 

When compiling the program, add the “-M” linker flag so link will generate a .MAP file for the application. This 
map file includes the name and segment address of every function called by the program. Run the MAPSYM utility 
program after the program is compiled and linked. This utility generates a SYM symbol file that is used by the profile 
report program to determine the names of the segments that were “hit” during profiling. 

With all of this done, you simply run the program. The profiler writes the “hit” data to the memory buffer during 
execution of the code between the ProfStart() and ProfStop() function calls. When the program is finished, the data 
will be stored in raw form in the CIPS.DATA file on the WINDOWS subdirectory. To get a readable analysis of this data, 
run the SHOWHITS.EXE program from DOS. SHOWHITS comes with the Windows SDK. SHOWHITS collects all of the 
hit data in the file, organizes it, and displays a report on the screen in the following format: 

C:\WINDOWS>showhits -3 


Windows Profiler Data Displayer 
Copyright (c) 1988-1990; Microsoft Corp. Alt Rights Reserved. 


Here are the Hits for Unrecognized Segments 
4 Hits on Segment 01AD 
Here are the Hits for Known Segments 
586 Hits on GENERIC-1 
6 Hits on KRNL386-0 
1 Hits on USER-O 
49 Hits on USER-15 
76 Hits on GDI-O 


777 Hits on DISPLAY-O 
' 30 Hits on SYSTEM-O 


1529 TOTAL HITS 


Profiler Summary (Top 10 Hits): 
- SHOWHITS.EXE allows several command line switches. They are 
SHOWHITS [-1/-3] [-ipath] [csips_file] [seg file] 
3 386 enhanced mode profiling. Implies that VPROD.386 was installed as a driver in SYSTEM.INI’s 


{386Enh] section. 
f* Real mode profiling. Implies that PROF.COM was run before Windows was started in real mode. 
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. -ipath shoes * 8 Specifies the directory path to locate the SYM file output by MAPSYM. 


sips file Specifies the full path name of the CIES. DAT file. one default, this file is in-the WINDOWS 
_ subdirectory. 
seg_file - Specifies the full path name of the SEGENTRY.DAT file. This file is generated when Windows 


starts, if the profiler has been installed. By default, this file is located in the WINDOWS 
\ subdirectory. 


Normally, you will just run SHOWHITS from the WINDOWS subdirectory with the “-8” switch. SHOWHITS will 
prompt you with a short help screen if you forget to set a switch. 


Using the Profiler 


Getting meaningful data out of the profiler is not as simple as it might appear. Most Windows applications spend the 
majority of their time executing Windows functions for output to the display and for other Windows activities. You 
tend to get a lot of hit data in the segments that Windows loads, such as USER, DISPLAY, and GDI. This information is 
not very helpful. 

If there are specific parts of the program that are calculation intensive, surround these sae with the ProfStart() 
and ProfStop() functions as closely as possible. Avoid having calls to Windows functions between the profile markers, 
particularly ones that require user response. For example, if the program calls MessageBox() between ProfStart() 

_ and ProfStop(), you know that most of the time will be spent waiting for the user to click the OK button, not in 

program execution. 

In general, you cannot compare the performance of two different but similar Windows functions within one ver- 
sion of the program. For example, you cannot compare the time spent by TextOut() and DrawText() by surrounding 
each of these calls with a ProfStart() and ProfStop() function. Both of these functions use portions of the same 
Windows .DLL files and end up contributing hits to the same segments. 

To compare Windows function performance, compile the same code section two different times. Each time, sur- 
round the function to be analyzed with the ProfStart() and ProfStop() functions. If the profiler sample rate is the 
same, the absolute number of hits that you collect will reflect the total time the function occupied. Comparing the 
total hits for the two different versions of the program will tell you which version is faster. 


Debugging Functions | 


A full discussion of the excellent CodeView for Windows (CVW) debugger i is beyond the scope of this book, However, cde 
_ the debugging functions are documented. In general, you will not need to.use any of these functions when debugging. - 


-. .. The debugger allows breakpoints to be set, conditions to be checked, ete. , without modification to the code other than cA 


"compiler switch settings. . : 
— A point’ worth noting is that ihe cvw debugger will wos fine in 386 enhanced “inde without installing the. 
» WINDEBUG.386 driver in the [386Enh] section of the SYSTEM.INI file. Not having the debugger driver installed will 
eliminate the possibility of breaking to the debugger with the (7RL)(atT)Gysreq) key combination, and also makes 
wag several of the debugging functions inoperative. These functions are not normally needed to debug a Program. 


es Execution Profiling and Debugging Function Summary | 


__ Table 26- I summarizes the Windows profiling and debugging functions. The next section conatins the detailed func- 
tion sseeul Mae 


DebugBireak Forces a break to the debugger. 


FatalExit Forces an immediate termination of the application. 
OutputDebugString Displays a character string at the bottom of the debug screen. 
ProfClear Clears all data from the profile sample buffer. - 


_ ProfFinish. Stops the profiler, and copies the data buffer to the disk file CSIPS.DAT. 
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ProfFlush — Copies the profiler sample buffer to disk. 


ProfinsChk Checks if the profiler has been installed. 

ProfSampRate Sets the sampling rate of the profiler. 

ProfSetup Initializes the size of the profile data buffer and disk file, 
ProfStart Starts the execution profiler. 

ProfStop Stops the profiler. 

ValidateCodeSegments Enables debugging checking if code segments are overwritten. 
ValidateFreeSpaces Enables checking of memory overwriting of free areas. © 


Table 26-1. Execution Profiling and Debugging Function Summary. 


Execution Profiling and Debugging Function Descriptions 
This section contains the detailed descriptions of the Windows profiling and debugging functions. 


DEBUGBREAK  gWin2.0 mWin3.0 mWin3l 
Purpose Forces a break to the debugger. . 
Syntax void DebugBreak(void); 

Description This function codes a debugger break right into the program. It is only used when debugging. 
Uses Not often used. It is usually easier to set breakpoints from within the debugger. 

Returns No returned value (void). 

See Also | OutputDebugString() 

Parameters ~ None (void). 

Example This example breaks to the debugger when the “Do It!” menu item is clicked. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


switch (iMessage) ; /* process windows messages */ 


case WM_COMMAND: “ ‘ ‘/* process menu items */ 
switch (wParam) — oan hat 


case IDM_DOIT: yt User hit the "Do it" menu item */ 

DebugBreak () 

break ; ; 
[Other program lines] 
FaTALEXxItT - 7 meWin2.0 m8 Win30 mWin31 
Purpose Forces an immediate termination of the application. . 
Syntax void FatalExit(int Code); 
Description This function is only used in debugging. It forces an immediate end to the program’s operation, 


bypassing WM_DESTROY processing logic and the message loop. It should only be called if the 
application cannot be shut down by any other means. 


Uses Used in debugging as an emergency way to shut down the application, in most cases without 
__ forcing Windows to shut down or fail. 
_ Returns _ No returned value (void). 
See Also DebugBreak() 
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Parameters . 

nCode int: The SDK documentation suggests that FatalExit displays this ¢rror code and message in the 
. debugger window. The message is not reliable. 

Example . 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ 


switch (iMessage) /* process windows messages */ 
{ 


case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
FatalExit (1) ; 
break ; 
[Other program lines] 
OvuTPUTDEBUGSTRING mWin20 mWin30 mWin3.1 
-Purpose - Displays a character string at the bottom of the debug screen. 
Syntax void OutputDebugString(LPSTR /pOutputString), 


Description This function is only used in debugging. The character string is ultimately added to the bottom of 
a the screen in the debugger. If no debug monitor is installed, the character string is sent to the 
AUX port (assumed to be connected to a terminal). 


Uses Handy for tracking which parts of a program were executed, and in what order. A series of differ- 
ent messages can be output, each at a different location. This procedure minimizes the disrup- 
tion to the program, compared to setting breakpoints in the debugger. 


Returns No returned value (void). 

Parameters 

lpOutputString _ LPSTR: Apointer to a null-terminated character string that will be displayed at the bottom of the 
debug monitor screen. 


Example This example outputs the string “Testing debug function” at the bottom of the debug screen when 
the user clicks the “Do It!” menu item. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG (Param) 
{ ; 


switch (iMessage).— /* process windows messages */ 
case WM_COMMAND: /* process menu items */ 
switch (wParam) 
{ ; : 
case IDM_DOIT: : /* User hit the "Do it" menu item */ 
OutputDebugstring ("Testing debug function") ; 
break ; 
[Other program lines] 
ProFrCLear . | Win2.0 mWin30 e8Win3.1 
Purpose Clears all data from the profile sample buffer. 
Syntax void ProfClear(void); 
Description The profile copies the hit data to a memory buffer while the profiler is active. This data is written 


to a disk file when ProfFlush() or ProfFirishQ) is called. The memory buffer can be emptied by 
calling ProfClear() in the program rah: profiled. This does not affect any profile data already 
written to disk. 
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Uses 
Returns 
See Also 
Parameters 
Example 
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Generally used at the start of a profiling session. 
No returned: value (void). 


. ProfFlush() 


None (void) 


This example profiles the operation of two functions. The Method1() function uses the TextOut() 
and wsprintf() functions repeatedly. Method2() just counts integers 10° times. To run the profiler, 
the profile device driver VPROD.386 must be added to the SYSTEM.INI file in the [886Enh] sec- 
tion with the line 


DEVICE=VPROD.386 


Windows must be restarted with this change in SYSTEM.INI before profiling begins. 

The program. must be linked with the linker switch, -m (for map), set on. After the program is 
compiled and linked, MAPSYM.EXE is run to generate a MAP file. When the program executes, it 
generates the file CSIPS.DAT in the \WINDOWS subdirectory. Running SHOWHITS.EXE as a DOS 


. eas fom: within the wee lsc! will miss the Te PuORaMON, 


: ee \WINDOWS>showhits =3- 


Windows Profiler Data Dieplayer 
Copyright (c) 1988-1990, Microsoft Corp. ALL Rights Reserved. 


Here are the Hits for Unrecognized Segments 


4 Hits on Segment O1AD 


Here are the Hits for Known Segments 


586 Hits on GENERIC-1 
» 6 Hits on KRNL386-0 
1 Hits on USER-O — 
49 Hits on USER-15 

76 Hits on GDI-0 
777 ~ Hits on DISPLAY-O 
30 Hits on SYSTEM-O 


1529 TOTAL HITS” 


Profiler Summary (Top 10 Hits): 


Five hundred and eighty-six hits were within the GENERIC application’s segment. The hits 
were times that the profile timer checked the application and found the current segment to be 
the application’s segment. These hits occurred in the Method2() function, which counts for a 
long period of time. The majority of the hits were detected in the DISPLAY and GDI segments. 
They reflect the repeated use of the TextOut() and wsprintf() Windows functions in the 
Method1() function. The remainder of the hits were in other portions of the Windows environ- 
ment used to process messages, etc. 

The program initializes the profiler for 2 millisecond intervals between checks when the 
WM_CREATE message is processed. The sample data buffer is set to 100K. The calls to 
ProfStart() and ProfStop() occur within the functions that are profiled. ProfFlush() is called 
between the two function calls to copy all of the profile data to disk before the second function is 
called. This reduces the chance of overflowing the buffer. 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) . 


int 


nProfMode ; 


switch (iMessage) ' /* process windows messages */ 
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.f£ 
case WM_CREATE: 
nProfMode = ProfiInsChk () ; 
if ('nProfMode) ' 
MessageBox (hWnd, “Profiler not installed", “Message", 
MB_OK) ; ; 
else 
{ 
ProfSampRate (1, 2) ; /* two milliseconds */ 
ProfSetup (100, 0) ; /* 100 kbyte buffer */ 
ProfClear () ; /* empty buffer */ 
} “ 
case WM_COMMAND: . /* process menu items */ : 
switch (wParam) 
{ 
case IDM_DOIT: 
Method1 (hWnd) ; /* try method! function */ 
ProfFlush (€) ; /* write samples to disk */ 
Method2 ChWnd) ;. /* try method2 function */ 
break ; 
case IDM_QUIT: 
ProfFinish ©) ; 
DestroyWindow ChWnd) ; 
i break ; noe 
}. 
break ; 
case WM_DESTROY: . 
PostQuitMessage (0) ; 
break ; 
default: 
; return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 


return (OL) ; 
} 


void Method1 CHWND hWnd) 
{ 


HDC hDC ; 
int i; 
char cBuf [128] ; 


ProfStart () ; 
hDC = GetDC ChWnd) ; 
for (i =0; i < 1000 - i++) 
TextOut (hoc, 0, 0, cBuf, wsprintf (cBuf, “%d", 1)) ; 
ReleaseDC (hWnd, hDC) ; 
ProfStop () ; 
3} ; 


void Method2 CHWND hWnd) 
{ 


HDC hDC ; 
int : i, i; 


ProfStart () ; 
hDC = GetDC (hWnd) ; 
SetBkMode (hDC, OPAQUE) ; 
TextOut (hoc, 0, 0, “Starting”, 8) ; 
for (i = 0; 1 < 1000 ; i++) 
{ 
for (j = 0; j < 1000 ; j++) 
’ 
} . 
TextOut (hdc, 0, 0, "Done Counting", 13) ; 
ReleaseDC (hWnd, hDC) ; ; 
ProfStop () ; 


878 


26. EXECUTION PROFILING AND DEBUGGING v 


PRroFFINISH mWin2.0 mWin3.0 mWin3.1 

Purpose Stops the profiler, and copies the data buffer to the disk file CSIPS.DAT. 

Syntax void ProfFinish(void); . 

Description While the profiler is running, the hit data is copied to a memory buffer. This function stops the 
profiler, and copies the data to the file CSIPS.DAT in the WINDOWS subdirectory. This file is part 
of the input to the SHOWHITS.EXE program that outputs the profiler findings. 

Uses Used at the end of a profile session. 

Returns No returned value (void). 

See Also ProfFlush() 

Parameters None (void). 

Example See the example under the ProfClear() function description. 

ProFF LUSH wWin2.0 mWin3.0 mWin3.1 

- Purpose Copies the profiler sample buffer to disk. : . : BERGE S 

Syntax void ProfFlush(void); . 

Description While the profiler is running, the hit data is copied to a sample buffer. ProfFlush() copies this 
data to the file CSIPS.DAT in the WINDOWS subdirectory and empties the memory buffer. This 
allows more data to be accumulated without fear of overflowing the buffer. It is not necessary to 
call ProfFlush() if ProfFinish() will be called before the buffer is full. ProfFlush() should not be 
run when the program may be processing an interrupt. 

Uses Used within the body of the program being profiled to copy the profile data to a disk file. 

Returns No returned value (void). 

’ See Also ProfFinish() 

Parameters None (void). - 

Example See the example under the ProfClear() function description. 

ProrinsCuk mWin2.0 mWin3.0 mWin3.) 

Purpose Checks if the profiler has been installed. 

Syntax int ProfinsChk(void); 

Description This function checks to see if the 386 enhanced mode device driver VPROD.886 has been in- 
stalled, or whether the PROF.COM function was executed before WINDOWS was started. 

Uses Verification that the profiler is available. 

Returns int, 0 if the profiler is not installed, 1 if PROF.COM was installed, 2 if VPROD.386 was installed. 

See Also ProfStart(), ProfSetup() 

Parameters None (void). 

Example See the example under the ProfClear() function description. 

ProFSaMPRATE mWin2.0 mWin3.0 mWin3.1 

Purpose Sets the-sampling rate of the profiler. 

Syntax void ProfSampRate(int nRate286,int nRate386); 
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Description 


‘Uses 
Returns | 
See Also 


Parameters. 
nRate286 


- This function allows the sampling rate that the profiler uses to be set. The sampling rate is the 


number of times per second that the sampler will check and record the part of the Progen that 
is active. ; 


Used in initializing the profiler. 
No returned value (void). 
Prof Setup() 


‘int: The sampling rate that the profiler will use in any mode except 386 enhanced mode. If 


nkateg69e is set, the nRate886 parameter is ignored. nRate286 can be any of the values in Table 
26-2. 


4 
2 
a 
a ae 
5 
6 
7 
8 
= 


> — 
pe — O&O 


13 


422. 070 oes 
244, 141 microseconds 
ee 488. 281 microseconds, ; 

976.562 microseconds oe 
1.953125 miliseconds 

3.90625 milliseconds 
7.8125 milliseconds 

15.625 milliseconds — 

31.25 miliseconds 

65.2 milliseconds — 

125 milliseconds 

250 milliseconds - 

500 milliseconds 


Table 26-2. Sampling Rates for Non-386 EnhancedMode Profiling. 


nRate386 


Example 


PROFSETUP 
.. Purpose . 
Syntax 
Description 


Uses 


Returns 
See Also. 


~~ int: The sampling rate in milliseconds for the application if it is running i in 386 enhanced mode. 
If nRate286 is set, the nRate286 parameter is apnore The nRate386value can be between | and . 


1,000. 
See the example under the ProfClear() function description. 


wWin2.0 Win30 mWin3] 
Initializes the size of the profile data buffer and disk file. . 
void ProfSetup(int nBufferSize,int nSamples); 


This function is only effective if Windows is running in 386 enhanced mode. If the function is not 
called, the sampling buffer defaults to 64K, and the output file size is not limited. 


Setting the sample buffer size and file size. This could be important if the system were a 
low on memory. 


No returned value (void). 
-ProfSampRate @) 
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Parameters 
nBufferSize — int: The side of the sample data memory buffer in kilobytes. This value must be between | and 
* 1,064. . 

nSamples int: Sets a maximum on the number of hits that will be recorded to the disk file. A value of zero 
allows unlimited sample data. . 

Example See the example under the ProfClear() function description. 

ProFSTART pWin2.0 mWin3.0 mWin3.1 

Purpose Starts the execution profiler. 

Syntax void ProfStart(void); . . 

Description Once this function is started, the profiler begins checking the application at the time interval 
specified by ProfSampRate(). The location within the program is recorded as a “hit” in the sample 
buffer each time it is checked. 

Returns No returned value (void). 

See Also ProfStopQ) 

Parameters None (void). 

Example See the example under the ProfClear() function description. 

ProFSTop aWin2.0 mWin3.0 mWin3.1 

’ Purpose Stops the profiler. 

Syntax void ProfStop(void); 

Description. This function stops the profiler. The data collected in the profile data buffer is not affected. The 
profiler can be restarted by calling ProfStart(). The new data will be added to the profile data 
buffer. 

Returns No returned value (void). 

See Also ProfStart() | 

Parameters None (void). 

Example See the example under the ProfClear() function description. 

VarimieeoueSuonents eWin2.0 mWin30 wm8Win3.1 

Purpose Enables debug checking if code segments are overwritten. 

Syntax void ValidateCodeSegments(void); 

" Description Enables output of debugging information if memory areas containing code segments are over- 
written by program operations. 

Uses Validity checking is enabled by default with the debug version of Windows, so this function is 
normally not needed. If code segment checking has been turned off by including the line 
Ckernel) 

EnableSequentChecksuni=0 
in the [kernel] section of WIN.INI, then eee will override this switch and 
enable checking. 

Returns — No returned value (void). 
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See Also ValidateFreeSpaces() 


Parameters ~. None (void). ° 
Example | _. This example shows an application that has the debugging memory validation functions set when 


the WM_CREATE message is processed. Calling these functions assures that any program actions 
that overwrite code or data areas will be trapped by the debugger. 


Long FAR PASCAL WndProc CHWND: hWnd, unsigned iMessage, WORD sbeeaey LONG LParam) 
{ a. 


switch (iMessage) /* process windows messages */ 
: , 


case WM_CREATE: 
ValidateCodeSegments O; 
Nay eer er uaronecee O; 
break ; . 
case WM_. COMMAND: /* process menu items */ 
switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
GlobalCompact (NULL) ; Loos 
break ; 

[Other program lines] 
VALIDATEFREESPACES | . Win2.0 m@Win3.0 mWin3.l 
Purpose Enables checking of memory overwriting of free areas. 
Syntax LPSTR ValidateFreeSpaces(void); . 
Description _ This function is only available with the debugging version of Windows. Free memory areas are 


portions of memory that have not been allocated with. GlobalAlloc() and that do not contain code. 
This function enables checking of these areas when memory access functions are used, to make 
sure that memory writing operations use only valid memory areas. . 

_ Two lines must be added to WIN.INI in the [kernel] section before using this function.. 
Ckernel] 


EnableFreeChecking=1 
EnableHeapChecking= 1 


Windows must be restarted if these lines were. not in place when the system was started. 
_ Once installed, free memory areas will be loaded with the value 0xCC. Global memory operations, 
‘such as GlobalAlloc() and GlobalCompact(), will cause memory cHene to start, which slows 


system performance. 
Uses Used only with the debug version of Windows. Use should be limited to tracking down memory .. 
re errors, as this function slows system performance. 
Returns LPSTR. This value is not used. 
See Also  _—__—-ValidateCodeSegments() 
Parameters | None (void). 
Example See the previous example under the ValidateCodeSegment() function description. 
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Microsoft added a hypertext help system to Windows 3.0. “Hypertext” refers to the ability to jump from one subject to 
another while reading a document. The Windows help system has several advantages for the developer. 


1. The help system will be installed on any computer running Windows 3.0 or later. The Windows INSTALL program 
puts the WINHELP.EXE file in the WINDOWS directory. 


2. The help system is fully integrated into the Software Development Kit (SDK). Your application can include con- 
text-sensitive help, automatically loading the help system when called. “Context-sensitive” means that a different 
part of the help file is displayed depending on what part of the program is active. 


3. Because all of the applications provided with Windows use the help system, users can be expected to have some 
familiarity with its operation. 
This chapter documents the help file support command to Windows 3.0 and 3.1. Version 3.1 additions are not 
discussed. 


Building a Help File 

Adding Windows help file support to your application is a three-step process. First, create a help document using a 
text editor. Special characters are used to mark key words, index entries, etc. Second, compile the document using 
‘the HC.EXE help compiler provided with the SDK. This creates a help file that is ready to use by the WINHELP.EXE 
program. Last, add calls to the WinHelp() function in your program. This function loads WINHELP.EXE, if it is not 
already running, and jumps to a specified location in the help file. 


Although in theory you can use any text editor to create the help document, in practice you are much better off if 


you use Microsoft Word for Windows. Besides being an excel- 
lent editor, Word for Windows supports all of the special char- 
acters needed to create help documents. The help compiler 
expects to read a file in the rich text format (rtf). Word for Win- 
dows will save and read files in this format, although it must be 
specified in each file save and open operation. 

The help document uses several techniques to code the in- 
formation the help compiler needs to figure out indexes and 
jump points to other parts of the file. Footnotes are used to la- 
bel parts of the file with names and index entries. The double- 

_ underline character style is used to mark jump points, Jump 
points are the words that the user can click with the mouse to 
jump to another part of the help file. Underlined text is used to 
mark definitions. Clicking a definition word pops up a small box 
containing the word’s meaning. The box disappears when the 


user releases the mouse button. The hidden text style (a char- 


_ acter style supported by Word for Windows) is used to put cross- 
‘reference strings into the documents. Cross-reference strings 
are the names of the labels that the help system will jump to 
when the user clicks an item. 


883 


fo Index] 
File-Commands:{ 
~ Opening-A-FileOpen_Filef] 
~ Closing-A-FileClose_Filef 
Edit-Commands:f 


~ Editing-A-FileFdit_Filef 


#.5--K-Opening-A-Filef] 
This ‘text area tells how to oper-afileNef Eile 


#.$.-K-Closing-A-File] 
This textarea’ tells ‘-how-to:close:a: lileDet File 


#$---KE diting-A-File] 
This-‘text-area'tells-how-to-edit-afileNef_ File. 


A disk file-containing-data{] 
Figure 27-1. A Help Document. 


WINDOWS API BIBLE fn rare aes 


Figure 27-1 shows a small help document with all of the special characters 
exposed. The top portion of the file is the index. Below that, separated by page 
breaks, are three help subjects and a definition of the term “File.” Each title is 


_ preceded by footnote characters. The footnotes contain the names and labels for . 


each page of the help document. . 
(Hidden text is exposed and indicated with a dotted underline. Page breaks are 
_ indicated by a continuous dotted line between pages. Tab characters are indicated 
by the arrows to the right.) 
The hypertext j jump destinations use the “hidden text” style (shown in Figure 
27-1 with a dotted underline). For example, if the user clicks the visible “Opening A 
File” item in the index, the help system will jump to the label “Open_File.” 
“Open_File” is a footnote label for the second page of the help document. If you 
" were to open the footnote entries for editing within Word for windows, the footnote 
list would appear as shown in Figure 27-2. 
In Word for Windows, footnotes are added by placing the cursor at the location 


where the footnote is to be added, and then selecting the Insert/Footnote menu . 


item. The footnote dialog box requests a “Footnote Reference Mark.” This box is 
_ where you enter the $, #, +, or K character. Word for Windows will then open the 
footnote editing area at the bottom of the screen, so that you can enter the label 
string for the footnote. The editor keeps the footnotes in the correct order, and it 
will jump to a footnote if you position the cursor within the text area while the 


Index 

* Index 

# Open File 

, Opening A File 

* File_Commands:10 
K File;Open File 

#* Close File 

> Closing A File 


* File _Commands:20. - 


K File;Closing Files. 
# Edit File 

Edit File 

* File Commands:30 


K File;Editing Files — 


# Def File 


_ footnote edit area is visible. Figure 27-2. Index Entries 


Jor the Hep Document. 
Help Document Special Characters 
When building the help document, you will.add footnotes and special character types to serious the hypertext 
jumps. Table 27-1 contains a list of the special characters. The characters preceding the word sopmnele? are the 
Foomol Reference Mark” characters used when peeing a footnote in the document. 


aie: a cciiext cis This i is a destination label that the help system can jump to. The point(s) 


# footnote 
. to jump from will be marked with double- underlined text, followed by the same context string in 
hidden text. . 
$ footnote Defines a title string, Title strings are optional. 
K footnote - Key word, Key words are used to build the list of search strings that the help Sain wil arene 
“a. for. They are not required, but are highly recommended. : 
+ footnote Browse sequence number. In the footnote definition you put a group subject name, a colon, 


a and an integer. Browse sequences mark the order that the eae will me viewed if the user 
clicks the browse buttons on the help system window. 


Double-underlined text (strike Marks a cross-reference point. The marked characters will be highlighted in color on the help 


. through text has the same effect) system. Clicking the mouse pointer on the highlighted characters causes a jump to another | 
_topic. The destination is named in hidden text immediately following the double-underlined text. 


Underlined text Marks a definition. The underlined characters will be highlighted in underlined color on the help : 
system. Clicking the mouse pointer on the highlighted characters causes a small window 
containing a definition of the term to appear. The definition is obtained from another topic. The 
topic is specified in hidden text immediately following the underlined text. 
* footnote 


Marks a buildtag. Buildtags are used to allow conditional compilation of parts of a help file. 


Table 27-1. Help Document Special Characters. - 
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Defining Hypertext Jumps and Index Entries | 


The critical aspect in creating the help document is marking topics with the # footnotes. They are the context labels 
that allow that point to be a destination for a hypertext jump. Normally, these labels will be on the first line of a page — 
(following a page break), as shown in-the example in Figure 27-1. The footnotes can be placed anywhere in the page if 
desired. 

To allow jumping to the point, you must do two things. First, the text string that will mark the jumping off point is 
typed using double-underlined characters. This mark is followed by the exact context label for the destination, typed — 
with hidden characters. Once compiled, the footnote markers and hidden characters are not visible in the help win- 
dow. The doub!e-underlined characters (the jumping off points) are highlighted in color. 

Creating an index using these techniques is simple. As shown in Figure 27-1, the top of the help file is normally 
the index. Each jumping off point is marked with double-underlined characters, followed by the hidden characters 
defining where to jump. Each of the destination subjects is on a separate page, with the top line of each marked with - 
the # footnote context string. Context strings can be up to 255 characters long, and can contain letters, numbers, 

periods, and underscore characters. Spaces between words are not allowed. Uppercase and lowercase letters are 
- treated as identical. 


Adding Search Strings and Bookmarks 


The K footnotes are also important. The help window includes a magnifying glass button marked “search.” Topics that 
have K footnote entries will appear in a list of subjects that can be searched for. The search feature allows the user to 
quickly locate information in a large file. With the footnotes shown in Figure 27-2, the search list would have four 
entries: “File,” “Open File,” “Closing Files,” and “Editing Files.” Searching for “File” within the help system would 
reveal three topics to jump to. “Open File,” “Closing Files,” and “Editing Files” would show single entries. . 

Key words can be up to 255 characters long, and can contain any ANSI character including spaces. A group of key 
words can be defined on one footnote line by separating them with a semicolon. Here is an example with four key 
words defined. 


K Files;Opening Files;Disk;Disk Access 


Titles are marked with $ footnotes. Titles appear in the help system bookmark list. Bookmarks allow the user to 
mark a location for future reference. Titles also appear in the “Topics found” section when the user searches for a key 
word. Titles and key words are usually used together. Titles can be up to 128 characters long, and can contain any 
ANSI character, including spaces. The entire line in the footnote entry is considered to be one title entry. 

Browse sequences, marked with + footnotes, are less critical. They allow the user to jump from one section to the 
next section in a logical order. In a large file, there will be a number of groups of subjects (pages) that logically fit 
together. Each can be organized in a separate browse sequence. In the simple example shown in Figures 27-1 and 27- 
2, there is only one group, labeled “File_Commands,” available to browse. Each + footnote is followed by a colon and 
an integer. The integer order sets the browse sequence. The help system will not allow browsing to go past the first or 
last entry in a browse sequence. Note that the browse-‘numbers are sorted in character order, not numerical order. To 
avoid confusion, you can precede the browse sequence numbers by zeros. For example, if you will be using browse 
numbers up to 999, code the number five as 005. 


Adding Bitmap Graphics 


The help system will display bitmap graphics i in the help window. Bitmap graphics can be useful to clarify subjects, 
although large bitmaps can take up a lot of disk space. 

The simplest way to add a bitmap to a help document is to paste it into a Word for Windows document. The bitmap 
is saved along with the file. Chapter 15, Bitmaps, includes the source code for a program that will “cut” bitmap images 
from any Windows application, and then allow them to be “pasted” into Word for Windows. 

If your word processor does not support direct cut and paste operations with bitmaps, you can still include bitmaps 
stored as files in your help document. There are three ways to do this, depending on whether you want the bitmap to 
show up on the left or right of the document, or to be fit in with the character data. Here are the commands. 
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{bme filename.bmp} Fits filename.bmp in with the text at this location. 

_ {bml filename.bmp} Puts the bitmap at the far left of the document. 
{bmrfilename.bmp} . Puts the bitmap at the far right of the document. 
Note that the bitmap file is the same in all three cases. Only the loction on the help document changes. - 


Compiling a Help File 
The help compiler i is called HC.EXE. HC reads a project fi file with the extension .HPJ that specifies how : a help aoe 
ment is to be built. The project file is a normal ASCII text file. Here i is an example. 


& HELPEX.HPJ Help Project File Listing. 


COPTIONSI 
TITLE=Help Example 


’ COMPRESS=true 


WARNING=1 

CMAP] oh 
Open_File 10 
Close File 20 
Edit_File 30 
CFILESI 


\c\work\helpex.rtf 


“Inthis example, the help document created by Word for Windows is called HELPEX.RTF. It is referenced in the 
[FILES] section of the project file. To compile this file and create the file HELPEX.HLP, use the following command 
line: é 


C:>HC HELPEX.HPJ 


Note that the project file name, not the help document, is passed to the help compiler. If the help compiler does 
not find an error during compilation, it outputs the finished help file, HELPEX.HLP. This file can be read into the 
Windows help program and examined. The help program can also be launched from within another program ume the 
WinHelp() function. 


Help Project File Options 


The help project file has a large number of options that allow control over the help compiler. The project file is a 

standard ASCII file, not the RTF format used for the help document itself. The structure of the project file is similar to 
. that of WIN.INI and the other Windows initialization files. There are six possible sections in a help project file: [Files], 

{Options}, [BuildTags], [Alias], [Map], and [Bitmaps]. Only the et section is required, although most project 

files will include some [Options] and [Map] statements. 


Project [Files] Section 


The [Files] section is where all of the document files that will be combined to form the complete help aynena are 
listed. A typical section is 

CFILES] 

HELPEX.RTF 


HELPINOX.RTF 
COMMON .RTF 


; The files are assumed to be in the same directory as the project file. The directory can be meee with the ROOT 
option, described later in this chapter. 


Project [Buildtags] Section 


The help compiler allows portions of the help document to be included or omitted based on settings in the project file. 
This ability is useful when you want one version of the help document to allow generation of two or more different help 
files. This might be the case if you are marketing beginner and advanced versions of the same program. 
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Implementing buildtags requires additions to both the help document and the project file. Within the help docu- 
ment, each section is preceded with a buildtag footnote. (This.is a footnote with the asterisk (*) as the reference 
mark.) The footnote text can contain one or more strings that are the “buildtags” for the section. For example, the 
footnote 

* Beginner, Advanced 


would code a section as being included if either the “Beginner” or “Advanced” option were defined in the BUILD 
option of the help project file. The footnote 


* Advanced 
would only add the section if the “Advanced” BUILD option were defined. 
All of the buildtags used in the document file should be listed in the help project file under the [Buildtags} 


section. Finally, you specify which build =tag or tags will be included during compilation with a BUILD command in 
the [Options] part of the project file. 


COptions] 


| BUILD=Advanced 


CBuildtags] 
Beginner , 
Advanced 


Project [Options] Section 


The [Options] section of the project file provides information to the help compiler. Here is an example [Options] 
section using every possible statement. 


COptions] 

BUILD=Advanced | Beginner 

COMPRESS=TRUE 

WARNING=3 

ROOT=C:\C\WORK 

INDEX=main_index 

TITLE=Help Example 

FORECEFONT=Modern a 

MAPFONTSIZE=8-12:12 a 
MULTIKEY= A : 2 ; ; ; 


The BUILD option controls which of the sections marked with bis sdtags will be added to the finished help file. 
Usually, this is just one key word. 


BUILD=Advanced 


You can also combine more than one buildtag with the logical operators & (AND), ! (OR), and ~ (NOT). Parenthe- 
ses can be used to group buildtag names. 

The COMPRESS option controls whether the final help file is stored in compressed form, or is left iaintewad 
Normally, you will set this value to FALSE during the development of the help file to save time. During the final 
compilation, set the value to TRUE to reduce the disk space taken up by the help file. Decompression i sh fast, so there 
is little value in storing the help files uncompressed. 

The WARNING option determines the amount of debugging information the help compiler generates. Level lis 
minimal output, 2 is medium, 3 is maximum output. Set this value to 3 during development. 

The ROOT option specifies the starting directory for all help compiler operations. Directory names listed in the 
FILES section are assumed to be subdirectories of the ROOT directory. You can get around this assumption by typing 
the full path name of a file, starting with the drive letter. 

The INDEX option sets which section of the help document contains the index. The name following the INDEX= 
key word must be a context string (marked with a # footnote). If no INDEX value is specified in the project file, the 
first topic is assumed to be the index by the compiler. This is usually the best way to organize a help document, so 
INDEX i is not often used. 
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The TITLE option specifies a character string that will be added to the caption bar of the help window: The string 
. Will be followed by “Help - Filename,” where Filename is the name of the file that was loaded. 

The FORCEFONT option causes the help compiler to convert all characters to the specified font. — fonts 
are a Windows resource, the text will not be displayed if the help file references fonts that are not installed on the 
user’s system. In these cases, use FORCEFONT to specify one of the fonts supplied with Windows (Courier, Helv, 
Modern, Roman, Script, Symbol, and Tms Rmn). 

MAPFONTSIZE allows conversions from one font size to another during the help file compilation. This option i is 
generally used with FORCEFONT to pick font sizes appropriate for the font that will be used. MAPFONTSIZE can 
convert either a single font size to another size, or a range of font sizes to one final size. Here are two examples. 


COPTIONS] | . 
MAPFONTSIZE=8:12 ; Convert all 8 pt to 12 pt 
MAPFONTSIZE=10-16:14 7; Convert all 10 to 16 pt to 14 pt 


MULTIKEY allows the creation of additional key word tables. By default, only the letter K footnotes go into a key 
word table. MULTIKEY allows other letters to be used, creating additional tables of key words that can be searched. 
Upper- and lowercase letters are not equivalent. The letters “K” and “k” are reserved. : 

To use the MULTIKEY option, specify the HELP_MULTIKEY option when calling WinHelp(). 


Project [Alias] Section 


The [Alias] section allows the help compiler to use one context string in place of another. You might use this option as 
an alternative to changing the footnote names within a help document. For example, to eliminate the “Edit_Info” and 
“Cut_Info” topics, and have the jump points destinations changed to “General_Edits,” use 

CALIAS 


Edit_Info=General_Edit 
Cut_Info=General_Edit 


If the [ALIAS] section gets too long, the help document. will be difficult to follow, so use this option with discretion. 


Project [Map] Section 


One of the best features of the Windows help system is the ability. to create context-sensitive help systems. Context- 
sensitive means that the help topic displayed will depend on the portion of the program that is currently active. 

To create context-sensitive help files, you must assign numbers to the context strings. Context strings are placed 
by inserting topics marked with # footnotes. The string in the footnote’s text for the # footnote is the context string. 
For example, the help document shown at the beginning of the chapter, in Figures 27-1 and 27-2, contained several 
context strings. Each context string can be assigned a number within the project file as follows: 


CMAP] P 
Open_File 10 
Close_File 20 
Edit_File 30 


The Open_File Context string asigned number 10, Close_File number 20, and Edit_File number 80. These num- 
bers are used when calling the WinHelp() function. 

Within the program calling WinHelp() te load the help file, the dwData parameter passed to WinHelp() is set 
equal to the context number. An example of this is shown under the WinHelp() function description. The help system 
will jump to this numbered topic when WinHelp() is called. 


Project [Bitmaps] Section 
If bitmap files have been referenced within the heip document using the bmc, bml, or bmr commands, the bitmap files 
must be listed in the help project file under the [Bitmaps] section. Here is an example. 


’ CBITMAPSI 
bit1.bmp_ 

bit2.bmp — 
c:\paint\bit3.bmp 
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Using the [Bitmaps} will only be necessary if you are using a text editor that does not support direct pasting of 
bitmaps into the help document file. 


Using the Help System 

Although the help system works well, it does not provide any method to debug a help document. In large help files, it 
is easy to end up with a missing context string footnote, or some other important marker. Missing string errors are 
noted by the help compiler, but they are not always easy to track down. The best cure for these development problems 
is prevention. Organize the structure of your help document before you start writing the text. Use a consistent set of 
naming conventions (such as preceding key words with “k_,” topics with “t_,” ete. ). You can use a Microsoft Excel 
spreadsheet to keep track of the various labels used. 


WINHELP eWin2.0 mWin3.0 mWin3.l 


Purpose Loads and/or IScates an entry in a help file accessed via the Windows help system. 
Syntax BOOL WinHelp(HWND hWnd, LPSTR IpHelpFile, WORD wCommand, DWORD dwData); 
Description This function allows an application to call the Windows help system. The help file is assumed to 


have been created by the HC help compiler. If the help system (a Windows program) is not active, 
it is loaded, and the help fileis read. If the help system is already viewing the help file, calling 
WinHelp() can be used to jump to a new location in the help file, or to close the help system. 
WinHelp() allows several methods of starting the help system at a specific point in the help file, 
which allows context-sensitive help systems to be created. 


Uses Used within applications to provide online help documents. 
Returns BOOL. TRUE if the function was successful. FALSE on error. 
Parameters . 
hWnd HWND: The handle of the window that is calling the help system. 
lpHelpFile LPSTR: A pointer to a null-terminated character string containing the name of the help file. The 


file name can include the full directory path if needed. The file is assumed to have been created 
by compiling a help document with the HC help compiler. 


wCommand WORD: Sets what action beecianiels is to take. This can be any of the values in Table 27-2. 


HELP CONTEXT Displays the help fi file, ren with a context ia. In this case, Supanil isa 30- bit elrecies 


integer. The integer’s value is set to match a number in the [MAP] section of the help project file. 
HELP_HELPONHELP Displays help on the help system. Both /pHelpFile and dwData are ignored. 
HELP_INDEX — Displays the help file, starting with the help file’s index. This assumes that there is only one 
index. For files with more than one index, use HELP_SETINDEX. 
HELP_KEY . Displays the help file, starting with a key word in the help file. In this case, dwData contains a 
OR pointer to a character string containing the name of the key word. 
HELP_MULTIKEY Displays help for a key word in an alternate key word table. This is used with the MULTIKEY 


option in the help preject file. In this case, dwData points to a MULTIKEYHELP data structure. 


HELP_QUIT Closes the help file and terminates the help system for this application. Other aes: use 
, of the help system is not affected. dwData is ignored. . 


HELP_SETINDEX Sets a help index in a file containing more than one index. The index is identified by placing the 
context string number in dwData. The context string number is set in the (MAP section of the 
help project file (see the following example). Calling WinHelp() with this option is always followed 
by calling WinHelp() a second time with the HELP_CONTEXT command. 


Table 27-2. WinHelp() Command. — 
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dwData DWORD: The DWORD value passed to the help system. The value’s meaning depends on the 
a wCommand option. See Table 27-2 for the description. — 
For the HELP_MULTIKEY option, dwData points to a MULTIKEYHELP data ia de- 


fined in WINDOWS.H as 
typedef struct tagMULTIKEYHELP 
{ ; 
WORD ‘mkSize; /* size of this structure */ 
BYTE .. mkKeylist; . - . 4* table footnote character */ 
BYTE szKeyphraseL1]; /* key word to start on. This */ 


/* string will contain more */° 
/* than one byte */ 
} MULTIKEYHELP; 


Example This example shows four uses of the WinHelp() function. When the user clicks the “Do It!” menu 
item, the HELPEX.HLP file is loaded and displayed starting 8 from the index. If the user presses 
the &n key, the same file is loaded, but it is started from the topic “Editing Files.” If the help file 


has already been loaded, the file jumps to this topic. Similarly, if the user presses the (2) key, the 
help file jumps to the context string labeled number 20. The labels are set in the help project file. - 


© HELPEX.HPJ Project File 


COPTIONS 
TITLE=Help Example 
COMPRESS=true 
WARNING=3 
FORCEFONT=Modern 
MAPFONTSIZE=8-12:10 


CMAP) 

Open_File 10 
Close_File 20 
Edit_File 30 
CFILES] 


c:\c\book3\helpex.rtf 


Item 20 is mapped to the context string “Close_File.” The final use of the WinHelpQ) function 
is to close the help system when the application terminates. This does not cause a problem if the 
help system is not currently loaded, or if two or more applications of the help system are in use. 
Only an active instance of this application is removed by calling WinHelpQ) with the HELP_QUIT 
command. 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
C ; a sa 


switch (iMessage) /* process windows messages */ 
t . . 
case WM_COMMAND: | /* process menu items */ - 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu item */ 
WinHelp (hWnd, ngTRee: htp", HELP_LINDEX, NULL) ; 
break ; 


case IDM_QUIT: 

DestroyWindow (hWnd) ; 

break ; : 
} N 
break ;. 

case WM_KEYDOWN: 
if (wParam == VK_ F1) 
’ WinHelp ChWnd, “helpex.hlp", HELP_ KEY, 
CDWORD) CLPSTR) “Editing Files") ; 

else if (wParam == VK_F2) 

WinHelp (hWnd, “helpex.hlp", HELP_ CONTEXT, 
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CDWORD) 20) ; sy 
break ; 
case WM_DESTROY: ; /* stop application */ 
WinHelp (hWnd, “helpex.hlp", HELP_QUIT, NULL) ; 
PostQuitMessage (0) ; ; : 
break ; 
default: /* default windows message processing */ 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 
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Dynamic Link Libraries(DLLs) have a reputation for being difficult to create. This reputation dates from the early 
days of Windows, when you had to write your own assembly language prolog, and when the unique aspects of program- 
ming within a DLL were not well documented. 

Today DLLs are simple to write and debug. DLLs offer major advantages to programmers over conventional librar- 
ies of functions that are included in the linking process when a program is compiled. DLLs do not have to be 
recompiled or relinked. Functions in a DLL can be used by another program by just referencing the function names in 
the IMPORTS section of the program’s .DEF definition file. Once loaded, the DLL functions can be used by any run- 
ning application on the system, without loading another copy of the DLL into memory. 

Because of these advantages, DLLs are the preferred way to program functions that are likely to be useful to more 
than one application. As your experience as a Windows programmer grows, your collection of DLLs will increase. You 
may find that DLLs are the best way to market libraries of functions. 


What Is a DLL? 


If you have been programming with the C language for some time, you are probably familiar with object libraries. All 
~ of the C library functions, such as printf() and strcat(), are stored in object libraries. You can also create your own 
object library using the LIB program. During the linking process, the linker copies the functions that are called within 
aC program from the library file, and adds them to the executable program. This is more efficient than just storing the 
functions in a compiled .OBJ objective file, as only the functions-that are used are copied into the finished .EXE file. 

Objective libraries are fine for an operating system like MS-DOS that only allows one program to run at one time 
(TSRs and other tricks are ignored here). Under Windows, objective libraries are not efficient. Windows programs 
would be enormous if every one had to have its own functions for output to the screen, message processing, memory 
management, dialog boxes, etc. 

The developers of Windows invented DLLs to allow several programs running at the same time to share a single 
copy of a group of functions. Almost all of the basic functionality of Windows is stored in DLL files with names like 
USER, KERNEL, and GDI. You can also create your own DLL files, as described in the next section. DLL files usually 
have the extension .DLL, although they can be named with the extension .EXE. 

The term “dynamic link” describes how DLLs work. With a regular objective library, the linker copies all of the 
library functions it needs and passes the exact function addresses to the program that calls the functions. With DLLs, 
the library functions are in a separate DLL file. The DLL file is not involved in the linking process when a Windows 
program is created. The program that calls a function in a DLL does not find out the address of the function until the 
program is running and uses that function. Only then does Windows find the function in the DLL and pass its address 
to the calling program. The result is that DLLs provide the ultimate in reusable code. Once a DLL is created, it never 
needs to be recompiled or relinked again. Any number of running spp eens can call functions in a single copy of 
the DLL loaded inte memory. 


Creating a DLL 


' DLLs are simpler to create than a full Windows program. You do not need to create a window, window class, or 
message loop. You will need to add two short functions, LibMain() and WEP(), that take care of starting and closing 
the DLL. The LibMain() function is called when a DLL is first loaded into memory. The function must always have the 
format 
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int FAR PASCAL LibMain CHANDLE hInstance, WORD wDataSeg, WORD wHeapSize, 
LPSTR LpszCmdLine) ; 


hInstance is the DLL’s instance handle. wDataSeq is the data segment, if the DLL has a local heap defined in the 
.DEF file (see below). wHeapSize is the size of the local heap. [pszCmdLine is a pointer to a null-terminated charac- 
ter string that can contain a command line string. The command line string will only be available if the DLL is loaded 
with the LoadModule() function. The command line is passed as the lpCmdShow element in the lpParameterBlock 
parameter passed to LoadModule(). 

The only thing LibMain() must do is to call UnlockData() to unlock the DLL’s data segment in memory (assuming 
that there is no special reason why a locked data segment is required). You can also put any initialization functions, 
such as allocating memory blocks, in LibMain(). . 

The other standard function is WEP(), which is an exit routine called ne before Windows removes the DLL from 
memory. The function must have the following format: 


void FAR PASCAL WEP Cint nParameter) ; 


The parameter nParameter will either have the value WEP_SYSTEMEXIT if Windows is being shut jean or 
WEP_FREE_DLL if Windows is just removing the DLL from memory. You can code functions, such as freeing allocated 
memory, into WEP(). A WEP() function is not actually required if there is no cleanup to do, as the DLL is removed 
from memory. The Windows SDK documentation strongly recommends including a WEP() function i in all DLLs, so it is 
a good idea to put one in even if it is not needed with the current version of Windows. 

Besides LibMain() and WEP(), the DLL consists of functions that you create and add to the library. These func- 
tions need to be declared as FAR, and they are usually declared as FAR PASCAL following the normal Windows 
function declarations. Any pointer passed to a DLL function must be a FAR pointer. 

Listing 28-1 provides an example of a DLL source code file. Besides the required LibMain() and WEP() functions, 
the library contains a single function called InStr(). This function locates a string /seCheck in the string lszString and 
returns the character position of the match. It returns —1 if there is not a match. Note that the function is declared 
FAR PASCAL, and it uses only FAR pointers (LPSTR is defined as CHAR FAR * in WINDOWS.H). 


© Listing 28-1. EXMAPDLL.C 


/* exmpdlil.c example dynamic link Library */ 
#include <windows.h> 


/* dll initiator function */ 
int FAR PASCAL LibMain (HANDLE hInstance, WORD wDataSeg, WORD iieankiee: 

LPSTR LpszCmdLine) 
{ 

if (wHeapSize > 0) 

UnlockData (0) ; 3 = 

/* any initialization code goes heres return 0 if initialization fails */ 

return (1) ; : : 
} 


/* check if lszCheck is in lszString, return match pos, -1 if no match */ 
int FAR PASCAL InStr (LPSTR LszString, LPSTR LszCheck) ; 
{ Bo act 


LPSTR . UpCheck, lpString ; Ba 

int nMatch, nPos ; 

nPos = 0 ; 

do f , is 
LpCheck = lszCheck ; i : ; 


UpString = lszString ; 
nMatch = 0 ; 
do ¢ 
if (*lpCheck == *LpString) 
nMatch++ ; 
else 
break; . 
} while (*lpCheck++ && ic seninassy-: 
if (natch == Lstrtlen (lszCheck)) 
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return (nPos) ; 
else 
nPost+ ; 
} while (C*lszString++) ; 
-peturn (-1) ; ; 


y 


void FAR PASCAL WEP Cint nParameter) —  /* ALL terminator */ 
{ 
return; 


- Ifyou examine the code the InStr() function, you will note that there is nothing special about it. The only special | 
consideration in writing this function in a DLL was to make sure that only FAR pointers were used. Once you have 
written the DLL source code, you will need to compile and link it. In this case, “linking” does not link the functions 


'- into another program. Linking simply creates the executable .DLL file. Like any Windows program, a .DEF definition 


file is required for linking. 

There are several differences between the .DEF file for a DLL and the .DEF file for a Windows application pro- 
gram. Instead of the NAME statement, DLLs use LIBRARY to name the file. DLLs do not have a STACK statement 
because the DLL will use the stack of any application that calls a function in the DLL. DLLs can have a local heap, so 
the HEAPSIZE statement is included. Note that SINGLE is added to the DATA statement. Because DLLs only have one 
data segment. Only one instance of a DLL is ever loaded, unlike Windows applications where multiple instances each 
have their own data segments. 

_ Listing 28-2 shows a typical>DEF definition file for a DLL. 


© Listing 28-2. EXAMPDLL.DEF Definition File 


LIBRARY EXAMPDLL 

DESCRIPTION ‘Example DLL 

EXETYPE WINDOWS 

STUB ; "WINSTUB.EXE' 

CODE | PRELOAD MOVEABLE DISCARDABLE 
DATA PRELOAD MOVEABLE SINGLE 
HEAPSIZE 1024 

EXPORTS InStr 


The EXPORTS statement in the DLL’s .DEF file is where the library function namesare. listed. Any application 
calling a function in the DLL will use this name to reference the library function. !t is easy to forget to add the function 
name to the .DEF file after adding a new function to the C program. _ 

The last adjustments needed to compile a DLL are made to the NMAKE file. Listing 28-3 shows the NMAKE file 
needed to compil@EXAMPDLL.C. The C compiler switch “-ASw’ is added. The “s” specifies the compiler small memory 
model. The “w” provides warning messages if the compiler detects the use of a NEAR pointer that assumes that the 
stack is in the local data segment (more on this later). You will use the “-AM” flag for a medium memory model 
compilation. 


XN 


©. Listing 28-3. EXAMPDLL NMAKE File 
# make file for exampdll library 


ALL: exampdll.dll 


_CFLAGS=-c -D LINT_ARGS -ASw -Zp -Ow -Gsw -W2 
eee /Jalign:16 


exampdll.obj: \exampdil.c bg 
. SCCC) SCCFLAGS) exampdll.c : 


exampdll.dtl: exampdll.obj exeuipdtks def 
link SCLFLAGS) exampdltl libentry, exampdlL.dll, NUL, Libw aeiee: exanpdil 
re exampdll.dLl 
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The NMAKE file includes the LIBENTRY.OBJ and the SDLLCEW.LIB files in the linker commandline. LIBENTRY 

_ isa small assembly language program that starts all DLLs and ultimately calls the LibMain() function in the DLL. A 

listing of this assembly language program is included in the LocalInit() function description later in this chapter. 
SDLLCEW.LIB is the standard objective library for all DLL files using the small memory model. 

As with Windows applications, the resource compiler RC.EXE is called at the end of the compile/link cycle. This 
example is so simple that no resource data was included. RC.EXE simply tags the DLL as being a Windows 3.0 version 
program. DLLs can include all types of resource data if desired. 

That is all there is to creating a DLL. When you are done, the file EXAMPDLL.DLL will be created. You can’t run 
this program from the file manager or program manager. It is only useful if the functions included are called by 
another Windows program. ; 


Using the Functions ina DLL 


Continuing with our example, let’s say that you want to use the InStr() function in the DLLi in a Windows program. The 
only requirement is that you add the function’s name in the IMPORTS section of the calling program's .DEF definition 
file. Listing 28-4 provides an example of a .DEF file for a program that uses InStr(). 


© Listing 28-4. GENERIC.DEF 


NAME GENERIC 

DESCRIPTION "generic windows program' - 
EXETYPE WINDOWS 
STUB ; "WINSTUB.EXE' 

CODE PRELOAD MOVEABLE 

DATA PRELOAD MOVEABLE MULTIPLE 
HEAPSIZE 1024 

STACKSIZE 5120 

EXPORTS WndProc 

IMPORTS EXAMPDLL.InStr 


The only thing special about this .DEF file is the last line. The program IMPORTS the function InStr() from the 
file EXAMPDLL. This is how you tell Windows where to find the InStr() function when GENERIC.EXE calls it. With 
InStrQ) listed in the .DEF file, you can use it within the.program like any other library function. Listing 28-5 provides 
an excerpt from a program calling thisfunction. . 
© Listing 28-5. Calling the InStr() Function from within a Windows Program 
int FAR PASCAL InStr (LPSTR LszString, LPSTR tszCheck) ; 


Long FAR PASCAL:WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 


Static char cBuf1 C1 = {"This is a string to check out."} ; 

HDC hDC ; 

char cBuf £128) ; 

switch CiMessage) /* process windows messages */ 

{ ‘ ; 
case WM_COMMAND: /* process menu items */ 


switch (wParam) 


case IDM_DOIT: /* User hit the "Do it" menu item */ 
hDC = GetDC ChWnd) ; 
TextOut (hDC, 0, 0, cBuf, wsprintf (cBuf, 
"String to Check->%s", (LPSTR) cBuf1)) ; 
TextOut (hDC, 10, 20, cBuf, wsprintf (cBuf, 
“check is at position %d", 
InStr (CLPSTR). cBuft, 
' (LPSTR) “check"))) ; 
TextOut (hDdDC, 10, 40, cBuf, wsprintf (cBuf, 
“other is at position %d", 
InStr (CLPSTR) cBufl, . 
; CLPSTR) “other"))) ; 
ReleaseDC (hWnd, hDC) ; 
break ; 
[Other program lines] 


+ 895. 


WINDOWS API BIBLE 


With this simple example, the function prototypefor =m generic | 
the InStr() function is coded right into the calling pro- Do It! Quit _ 
gram. For a larger DLL, the DLL’s exported functions 
would be prototyped in a header file that could be in- String to Check) This | is a string to check out. 
cluded in any program calling the functions. check Is at postion 20 ‘ 

, InStr() is called twice in the example. Note that the 
narameters passed to InStr() are cast to long pointers. Figure 28-1. Output from Oe Calling InStr(. ) 
This explicit calling is not necessay if you use afunction DLL Function. 
protypefor InStr(). This example will produce the output 
shown in Figure 28-1 when the user clicks the “Do It!” menu item. 


Other Ways to Call DLL Functions 


The previous example used the most common method of providing Windows with the function address to use in the 
DLL: reference by function name. This method works for any number of functions in a DLL. For example, if the DLL 
has three functions, the EXPORTS section of the DLL's .DEF definition file would look like 

EXPORTS FirstFunc 


SecondFunc 
ThirdFunc 


other is at postion -1 


If the DLL file’s name is MYDLL.DuL, then any program wanting to use these three functions would include the 
following in its .DEF definition file: 
IMPORTS MYDLL.FirstFunc 


MYDLL.SecondFunc 
MYDLL.ThirdFunc 


Amore efficient, but less transparent, method of linking the functions is to give each exported functiona number. 
These numbers, called “ordinal” numbers, are preceded by an eayereane (@) character in the DLL's EXPORT sec- 
tion. Here is an example. 


EXPORTS FirstFunc a1 
SecondFunc a2 
‘ThirdFunc a3 


' The program using the DLL's functions can then IMPORT them based on the ordinal value. 


IMPORTS FirstFunc = MYDLL.1 
SecondFunc = MYDLL.2 
ThirdFunc = MYDLL.3 


This produces smaller and faster code than using the function names to define the link. The trade- off is that it is 
easy to get the ordinal numbers confused when using large DLL files. ; 

One trick that you can use with either the function name or ordinal number methods of linking DLLs is to rename 
the function within the program's .DEF file. For example, the program calling the three functions could have the 
following lines in its .DEF definition file: 


- IMPORTS FirstF = MYDLL.FirstFunc 
SecondF = MYDLL.SecondFunc 
ThirdF = MYDLL.ThirdFunc | 


This is called giving the function an “alias.” You can do a lot of clever tricks using function alias names, such as 
replacing standard Windows functions with your own versions. Again, the trade-off is that the code gets more difficult 
to follow when the same function may have move than one name. 
The last way to link a DLL’s functions to a program is to explicitly load the library with the LoadLibrary() func- 
__ tion, and obtain a function address with GetProcAddress(). This provides precise control of when a DLL is loaded into 
memory, and when it is removed with FreeLibrary(). Using these functions is more complex than defining the links in 
the program .DEF files, as you must use indirect function references. An example i is provided under the ipa he 
function pena: 
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Importing Windows Library Functions 


All of the examples used in this book import functions from the Windows DLLs that contain functions like 
ShowWindow(), TextOut(), etc. You may wonder why we have not had to include a long list of function names in the 
IMPORTS section of every .DEF file to allow links to the Windows functions. 

The answer is that Windows allows you to summarize all of the functions that are exported from a DLLin a small 
file that the linker can read. This file is called an “imnort library.” The IMPLIB.EXE program creates this ‘type of file. 
IMPLIB has the following syntax: 


IMPLIB imp-lib-name mod-def-file 


Where imp-lib-name is the name of the import library file to create, and mod- def-file is the name of the DLL’s .DEF 
definition file. For example, to create an meee library for EXAMPDLL. DEF, you would use the following command | 
line from DOS: 


IMPLIB EXAMPDLL.LIB EXAMPDLL. DEF 


Once this is done, you can forget about all of those IMPORT statements, and just use the import library inthe . 
LINK command line. For example, 


LINK GENERIC, GENERIC.EXE, , /NOD SLIBCEW LIBW EXAMPDLL, GENERIC.DEF 


would give the linker the dynamic link function information to link the EXAMPDLL functions into GENERIC.EXE at 
run time. 

You have probably figured it out already, but the SLIBCEW and LIBW import libraries of Windows functions were 
created this way. We have included them in every LINK command for the examples in this book. That is how the DLL 
functions for all of the Windows library are referenced into the programs. 

All links of Windows programs include the LIBW.LIB import library. The other Windows import library you will 
include in the LINK command line depends on the memory model, math calculation basis, and whether the program 
to be created is a Windows application or DLL. Table 28-1 summarizes the import ubraty names. 


:Memory Mc “oi. For an Application Program’ © 
eee Eraiation Math Routines 
Small SLIBCEW.LIB SDLLCEW.LIB . 

Medium  MUBCEW.LIB MDLLCEW.LIB 

Compact CLIBCEW.LIB CDLLCEW.UB 

Large LUBCEW.LIB LDLLCEW.LIB 

Altemate Math Routines e 

Small | SLIBCAW.LIB , SDLLCAW.LIB 

Medium : MLIBCAW.LIB MDLLCAW.LIB 

Compact CLIBCAW.LIB CDLLCAW.LIB 

Large LUIBCAW.LIB LDLLCAW.LIB 


Table 28-1. Windows Import Library Names. 


The compact and large memory models are not often used in Windows programs, as they require the program's 
code to be fixed in memory. If you are not familiar with the memory models or math calculation options, you may want 
to review your C compiler manual. 


Problems with Writing DLLs | 


We briefly mentioned in the description of creating a DLL that the DLL uses the calling program's stack. The DLL 
does not have a stack of its own. This is different from a conventional Windows application, where the stack and the 
local — share the same ae ican This difference c: can cause problems if you are . aware of its ae: 
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(If you have some assembly language background, you may find it simpler to think of the differences between a 
Windows application and DLL in terms of the CPU’s registers. With an application, the stack segment and data seg- 
ment are the same. That is DS == SS. With a DLL, the stack segment belongs to the calling program, and the data 
segment belongs to the DLL. DS != SS.) 

Some C compiler library functions take shortcuts that make the assumption that the stack and the local heap are 
in the same segment. These functions will cause the DLL to attempt to write in a protected area of memory and cause 
the-application to fail. You can also fall into the same trap if you use automatic variables inside the DLL for pointers. 
or arrays. Short pointers for automatic variables will point to the stack of the calling program. Short pointers for static 
variables will point to the local heap. You can get all sorts of incorrect nolan if you are not careful. 

There are several simple ways to avoid these problems. 


1. Use FAR pointers. FAR pointers code both the segment and the offset for an address. It does not matter if the 
pointer points to another application’s stack, or the DLL's memory heap. The pointers will be valid. 


2. -Use static variables. Static variables are always stored in the local heap, not in the stack. This rule avoids the DS 
!= §$S problem, but may waste memory if the variables are only needed for a short period of time. 


3. Use third-party C library functions with caution. The C library that comes with the Microsoft 5.0 and later compil- 
ers is safe, but most non-Windows code is suspect. 


__ Static variables have their own set of pitfalls inside DLLs. Remember that any number of applications can call the 
same DLL functions. Imagine a database application that uses one function call to move to the first record and stores 
this location in a static variable. While the first application is working on the database, a second application can call 
the same function and reset the static variable to a new value. The first application will not be alerted to this, but the 
static value will suddenly be invalid. 

_ Avoiding these types of problems requires careful DLL design. Assume that all DLL functions are potentially 
reentrant. That is, the function can be called independently at different times by separate applications. If you need to 
store data specific to one application’s use of the DLL, allocate separate memory for each calling application. The 
application’s instance handle is a good choice fora parameter to pass to the DLL's functions so that calling applica- . 
tions can be differentiated. 


Debugging DLLs 


_ The CodeView for Windows debugger works perfectly for DLLs. When you initiate the debugger, you will need to enter 
the name of the application that calls the DLL and the name of the DLL(s). After that, the DLL will behave just like 
any other file that the debugger processes. You can set breakpoints in the DLL, examine registers, etc. 

Use the same -Zi -Od compiler switches to disable optimization and add debugging information when creating a 
DLL. Here is an example NMAKE file, preparing the EXAMPDLL.C file for ere 


# make file for exampdll Library 
ALL: exampdll.dLll 


CFLAGS=-c -D LINT_ARGS -ASw “Zip. ~od ~Gsw -We 
LFLAGS=/NOD es fatigns 16 


éxaepatls. obj: exampdlt.c 
$(CC) SCCFLAGS) exampdll. c 


exaupall dll: exampdLl. obj exampdll .def 


link $(LFLAGS) exampdtt Libentry, exampdll.dll, NUL, Libw sdilcew, exampdll 
re exampdll.dtl 


Dynamic Link Library Function Summary 


Table 28-2 summarizes the functions that support the DLLs in Windows applications. The next section contains the 
detailed function descriptions. 
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ela Removes a DLL library from memory. 


GetProcAddress Retrieves the address of a function in a DLL. 
LoadLibrary Loads a DLL into memory. 
Localinit Initializes the local memory heap during the startup of a DLL. 


Table 28-2. Dynamic.Link Library Function Summary. 


Dynamic Link Library Function Descriptions . 
This section contains the detailed description of the functions that support using DLLs in Windows applications. 


FREELIBRARY mWin2.0 mWin3d.0 gm Win31 

Purpose Removes a DLL library from memory. ~ 

Syntax void FreeLibrary(HANDLE hLibModule); 

Description LoadLibrary() and FreeLibrary() directly control shen a DLL is loaded and removed from ~ 
memory. DLL library modules are only loaded into memory once. If more than one call to Load- 
Library() is made, Windows keeps track of the number of loads as the reference count. Each call 
to FreeLibrary() reduces the reference count by one. When the reference count reaches zero, the 
DLL module is removed from memory. 


Uses | Each call to LoadLibrary() should have a matching call to FreeLibrary() to make sure that the 
DLL is not left in memory after the user applications are terminated. 

Returns No returned value (void). 

See Also LoadLibrary(), GetProcAddress() 

Parameters 

hLibModule HANDLE: The handle of the DLL library module. This value is returned by LoadLibrary(). ~ 

Example This example demonstrates explicitly loading and freeing a dynamic link library. In this case, the 


‘InStrQ function in the EXAMPDLL.DLL library (discussed at the beginning of the chapter) is 
used. The program using InStr() does not include the library and function name in the IMPORTS 
section of its .DEF definition file. Instead, LoadLibrary() is used to load the library when the 
WM_CREATE message is processed. Figure 28-2 shows the example program after the .DEF menu 
item was selected. 

The library file EXAMPDLL.DLL is loaded by calling LoadLibrary(). If the returned handle 
has a value greater than 31, the library was successfully loaded. GetProcAddress() returns the 
address of the InStr() function within the library, so that the function can be called. 

One trick here is the definition of the pointer to the InStr() function. The top line in the 
listing shows a typdef of the INSTR data type. INSTR is defined as a function that has the same 
type and parameters as the InStr() function in the ccna This data se is used to create the 
lpFuncinStr static pointer for the ers 


InStr() function. This avoids getting ae: ae ; + cn a generic ot : 

compiler warning messages every Do lt! Quit 

time the function is called. String to Check->This is a string to check out. 
The InStr() function is actually check is at postion 20 : 

used in the processing of the other Is at postion -1 


WM_PAINT messages. The function 
is called indirectly, using the Figure 28-2. FreeLibrary() Example. 
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lpFunclnStr pointer. This is done twice, checking the occurrence of two strings within the. 
cBuf1[] character array. The results are output to the window's cient area pa with a combination of 


the TextOut() and wsprintf() functions. 


‘When the program terminates, the library is removed’ from memory with a call to Free- 
Library(). If another running application is using EXAMPDLL.DLL at the same time, Free- 
Library() will just reduce the library's reference count by one. The library will not be removed 
from memory until all applications using it have terminated, or called FreeLibrary(). 


typedef int (FAR PASCAL *INSTR)C(LPSTR, LPSTR) ; 


Long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG Param) 
£ 


sie : : /* default windows message processing */ 
return DefWindowProc ChwWnd, aman seaee wParam, lParam) ; 
ane (OL) ; , / 
GetProcApprEss | o —mWin20  mWin30  mWindt 
Purpose Retrieves the address of a function ina aynanie link library (DLL). 
Syntax 


static char cBuf1 €] = ("This is a string: to check out."} ; 

HDC hDC ; 

char : cBuf £128) ; 

static HANDLE hLibrary ;. : 
static INSTR UpFuncInStr ; 


switch (iMessage) 
{ 


case WM CREATE: 
. ‘ hLibrary = LoadLibrary CPEXAMPOLL. DLL") ; 
if ChLibrary < 32) 


/* process windows messages */ 


{ : 
MessageBox (hWnd, "Could not load dts 
“LoadLibrary Error", MB_OK) ; 
DestroyWindow ChWnd) ; 
} f 
- tpFuncInStr = GetProcAddress (hLibrary, "InStr") ; 
-break 7 
case WM_COMMAND: /*®* process menu items */ 
switch (wParam) 
{ 
case IDM_DOIT: /* User hit the "Do it" menu-item */ 


HDC = GetDC (hWnd) ; 


Textout Choc, oO, rie cBuf, wsprintf (cBuf, 


“String to Check-~>%s", CLPSTR) cBuft)) ; 
‘Textout (hd, 10, 20, ‘cBuf, wsprintf (cBuf, 


“check is at position 4d", 


(*lpFuncinStr) CCLPSTR) chutl, 
CLPSTR) “check"))) ; 
TextOut (hDC, 10, 40, cBuf, wsprintf (cBuf, 


eas is at position 4d", 


(*lpFuncInstr) (CLPSTR). eputt, 


ReleaseDC (hWnd, hDC) ; 
break ; 
case IDM_QUIT: 
DestroyWindow ChWnd) ; 
break ; 
} oe 
break ; 
case WM_ DESTROY: /* stop application */ 
FreeLibrary HEIDE SRY? 7 
PostQuitMessage (0) ; 


FARPROC GetProcAddress(HANDLE hModule, LPSTR lpProcName); 
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Description 


This function returns the address of a function in a DLL. It is equivalent to MakeProcInstance() 
which returns a function address for a Windows application module. The lpProcName function 
name must be listed in the EXPORTS section of the DLL's .DEF definition file. Normally, 
lpProcName points to a null-terminated character string containing the exported function name. 
Alternatively, if the function is given an ordinal value in the EXPORTS section, 


EXPORTS FunctionName ai 


the function can be referenced by using the MAKEINTORESOURCEO) macro 


FARPROC fekuaciaus 


fpFuncName = GetProcAddress (hLibrary, MAKEINTORESOURCE (1)) ; 


Uses 


Returns 


See Also - 


Parameters 
hModule 


lpProcName 


‘Example 


LoapLiprary - 


Used with LoadLibrary() to obtain a function address within a loaded DLL, so that the function 
can be called. 

FARPROC, the function’s address (entry point), Returns NULL on error. Note that if an incorrect 
ordinal value is used to reference the function, GetProcAddress() may still return a non-NULL 
value. 


MakeProcInstance(), LoadModule() 


HANDLE: The handle of the library module that contains the module. This value is returned by 
LoadLibrary(). Set hModule to NULL to reference the current module (the module that contains 
the GetProcAddress() function call). 


LPSTR: A pointer to a null-terminated character string containing the nanction name. Alterna- 
tively, this can be the ordinal value of the function, as listed in the EXPORTS section of the DLL's 
.DEF definition file. The spelling of the function name must be identical to that used in the 
EXPORTS section of the DLL's .DEF definition file. 


‘See the example under the FreeLibrary() function description. ~ 


mWin2.0 @Win3.0 mw Win31 


Purpose Loads a dynamic link library (DLL) into memory. a 


Syntax 


Deseription 


Uses 


Returns 


HANDLE LoadLibrary(LPSTR IpLibFileName); - 


This function provides an alternative to simply adding the DLL function names to the IMPORTS 
section of the .DEF definition file for the program calling the library functions. LoadLibraryQ) 
loads the DLL into memory and returns a handle to the DLL. The GetProcAddress() function can 
then be used to obtain the address of functions within the library. 

Ideal if a DLL will only be used for a small portion of the application. The DLL can be loaded, 
used, and then freed using FreeLibrary(). . 

HANDLE, the handle of the library. This value will be over 31. Otherwise, an error has occurred. 
The type of error is determined by the returned value, which may be any of the codes listed in 
Table 28-3. 


om © NM © 


Out of memory. 

as File not found. . 

' Path not found (invalid directory path specified in [pLibFileName). 
Attempted to load a task, not a DLL. 
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Table 28-8. continued 


Library requires separate data segments for each task. 
Wrong Windows version. 

Invalid .EXE file (DOS file, or error in program header). 
OS/2 application. 

DOS 4.0 application. 

Unknown .EXE type. 


Attempt to load an .EXE created for an earlier version of Windows. This error will not occur if 
Windows is run in real mode. 


Attempt to load a second instance of an .EXE file containing multiple, writeable data’ segments, 
EMS memory error on the second loading of a DLL. 
Attempt to load a protected-mode-only application while Windows is running in real mode. 


Table 28-3. LoadLibrary() Error Codes. 


See Also 


Parameters 
_ lpLibFileName 


Example 


Loca.Init 
Purpose 
Syntax 
Description 


Uses 


Returns 
See Also 


Parameters 
wSegment 
pstart 


pEnd 


FreeLibrary(), GetProcAddress() 


LPSTR: A pointer to a null-terminated character string containing the library name, The name 
can contain the full DOS path name if necessary. 


See the example under the FreeLibrary() function description. 

wWin2.0 mWin3.0 mWin31 
Initializes the local memory are during the startup of a dynamic link library (DLL). 
BOOL Localinit(WORD wSegment, WORD pStart, WORD pEnd); 


During the creation of a DLL, the LIBENTRY.OBJ module is linked into the program to add the 
startup routine for the DLL. LIBENTRY.OBJ is the standard startup routine for DLLs, provided 
with the Windows Software Development Kit. The source code (shown below) for this file is an 
assembly language function that does two things: 


1. Initializes the local memory heap for the DLL by calling Localinit(). 
2. Calls the LibMain() function in the C language source code file for the DLL. 


LocalInitQ) leaves the local heap as a locked memory segment. Normally, this is unlocked in the 
LibMain() function by calling UnlockData(). The heap can end up moved if either LocalAlloc() or 
LocalReAlloc() is called. Use LockData() to explicitly lock the heap memory block. 


Normally, not called from a C program because the inclusion of LIBENTRY.OBJ in the creation of 
a DLL takes care of this function call. 


BOOL. TRUE if the heap was initialized, FALSE on error. 
LockData(), UnlockData() 


WORD: The segment address of the segment that will contain the local heap. 
PSTR: The address of the start of the local heap within the segment. 
PSTR: The address of the end of the local heap within the segment. 
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Example This is the source code for the LIBENTRY.OBJ file that is included during the link step in the 
creation of a DLL. LIBENTRY calls LocalInit() to create the application’s local memory heap, 
- and then calls the LibMainQ() function within the DLL to allow the DLL to do initialization. 


AGE,132 
eooeeeeseeroneseeeseeeeceseesasecen . eseesesecceon eeseeseseeasessaeeeneese enesecen 
a a i i i i i i i i i i i i i i A ee a ee POTETIITEITEOOEEEOPEROPTETEEOEEPELEGLODETOR 


LIBENTRY.ASM 
Windows dynamic Link library entry routine 


This module generates a code segment called INIT_TEXT. 
It initializes the Local heap if one exists and then catls 
the C routine LibMain() which should have the form: 
BOOL FAR PASCAL LibMain(HANDLE hInstance, 
WORD wDataSeg, 
WORD cbHeap, 
LPSTR tpszCmdLine); 


The result of the call to LibMain is returned to Windows. 
The C routine should return TRUE if it completes initialization 
successfully, FALSE if some error occurs. 


Re Me Te Ve Ne Ve We Ne Vo Ve Ne Ne Te We Ne Vs Ya Ns “Y 


FEO OTTEETETOOTOPEIITEOPFELTTOTEIVOTEPPTOOOETFEPOTSOROEEE 


Srrercrrvrrreese 


. 
Ne 


include cmacros.inc 


externFP <LibMain> >; the C routine to be called 

createSeg INIT_TEXT, INIT_TEXT, BYTE, PUBLIC, CODE 

sBegin INIT_TEXT 

assumes CS,INIT_TEXT 

2PLM=0 3 'C'naming 

externA <_acrtused> 3 ensures that Win DLL startup code is Linked 
2PLM=1 7 "PASCAL' naming : 

externFP <LocalInit> ; Windows heap init routine 


cProc LibEntry, <PUBLIC,FAR> -; entry point into DLL 


cBegin = 
push di 3; handle of the module instance 
push ds ; library data segment 
push cx ; heap size 
push es 3 command Line segment 
push si 3; command line offset 


3 if we have some heap then initialize it 
jcxz calle 3 jump if no heap specified 


3 call the Windows function LocalInit() to set up the heap 
7 LocalInit((LPSTR) start, WORD cbHeap); 


xor ax,ax 
cCall LocalInit <ds, ax, cx> 

or ax,ax ; did it do it ok ? 
jz error ; quit if it failed 


7 invoke the C routine to do any special jnteietization 
calle: 
call LibMain 7 invoke the 'C' routine Cresult in AX) 
jmp short exit ; LibMain is responsible for stack clean up 


error: , 
pop si ; clean up stack on a LocalInit error 
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pop “es 
pop. .cx 
pop. _.ds 
pop di. 
exit: 
cEnd 


sEnd INIT_TEXT 
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Multiple Document Interface (MD!) 


Multiple Document Interface (MDI) is a standard way to write applications in which one master window holds a 
number of child windows. The most popular Windows program that uses this interface is Microsoft Excel, although 
many other programs also use it. Excel will hold a number of spreadsheets, charts, and macro sheets within the 
bounds of the Excel main window. 

Realizing that this type of program interface could be used for many types of programs, IBM included a iene 
tion of the proper behavior of, an MDI application in the book Systems Application Architecture, Common User 
Access, Advanced Interface Design Guide (IBM, 1989). This book describes how all windowing applications should 
behave, including complex applications like MDI programs. Microsoft added several functions to Windows 3.0 that 
make creating MDI applications simpler. These functions, and related MDI messages, are discussed in this chapter. 


MDI Frame and Child Windows 
Windows 3.0 includes a little-known application called SYSEDIT.EXE. By default, it is loaded in the SYSTEM 
subdirectory. SYSEDIT allows you to edit the initialization files CONFIG.SYS, AUTOEXEC.BAT, WIN.INI, and SYS- 
TEM.INI. Figure 29-1 shows a typical session. In this 


case, the child windows are cascaded, so that at least a a ae a System, Configuration Editor. [~ [= 
part of each window is visible and can be activated by a Eile Edit Search Window 
mouse click. 2 Za 

SYSEDIT is a classic MDI application. The outer CACONFIG.SYS --- Seuss 
window, called the “frame” window, contains all of the - aan CAAUTO EXEC, BaT 


child windows. Each child is a separate editor applica- J Do nT oe \WINDOWSIWIN. INI 
tion. The child windows can be minimized to an icon, | 
shown within the bounds of the frame. Children can also 
be maximized to fill the entire frame, covering up all 
other child windows below them. 

MDI applications end up being their own “little 
world.” All the child windows stay within the bounds of 
the frame window, and all use the same menu. This pro- Figure 29-1. SYSEDIT.EXE MDI Application. _ 
vides a consistent feel to the elements of an MDI appli- 
cation. The trade-off is that the child windows are limited to the size limits of the frame window. This contrasts with 
applications that use popup windows that can be placed anywhere on the screen. Popup windows are usually better 

-for relatively independent windows, while MDI child windows are best suited to closely coupled applications. 

One interesting aspect of the MDI child windows is that they do not have their own menus. All MDI windows share 
the same menu line on the outer frame. If there are different modes (such as graphics vs. spreadsheet child windows), 
the menu items may be different. To minimize confusion for the user, the menus should be as similar as possible. 


The Structure of an MDI Application 


You can create MDI applications without using special functions. Child windows will minimize to within the bounds of 
their parent's client areas, and they will display an icon when minimized. Child window extents are ‘automatically 
limited by the parent window's borders. The advantage of using the new MDI functions and messages is that Windows 
developers have provided direct implementations of several useful features. 
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1. The MDI frame menu can automatically keep a list of the names of all active child windows. You can take advan- 
tage of this feature to allow the user to select any active child from the menu item, even if the child window is 
hidden under other children. . 


2. Special messages are provided which automate the arrangement of the child windows into cascades (as shown in 
Figure 29-1), or tiled windows to fill the frame window's client area with all of the child windows. 


3. If some of the children have been minimized, a single message will arrange the icons at the bottom of the frame 
window’s client area. The program manager (an MDI application) uses this feature to arrange icons at the bottom 
of the client area. 


To implement these features, Windows 3.0 adds the MDICLIENT predefined window class. This class is similar to 
the definition of BUTTON and LISTBOX classes. You do not have to register predefined classes, they are already 
defined within Windows. 

‘The MDICLIENT window class runs the client area of the frame window. When starting, the MDI application. 
creates a frame window, then an MDICLIENT window as a child of the frame, and then all child windows as children 
of the MDICLIENT window. The structure is shown in — 

Figure 29-2. 
This arrangement allows the MDICLIENT window to 
~ take care of activities like cascading child windows or. 
arranging icons. You will not draw on the MDICLIENT 
window. Its sole purpose is to control the behavior of the 
child windows. The child window client areas and the 
frame window menu are the areas of an MDI application 


that respond to user actions. : “Child 1 i Child 3 


With the tree structure of windows in an MDI appli- 


cation, the most efficient way to communicate between CSERE TEAST ; ~. , 
the frame, MDICLIENT, and child windows is via Win- Figure 29. 2. Window Srichive§ in an 2 MDI ‘Application. 
dows messages. To automate default keyboard actions, 

the TranslateMDISysAccel() function is added to the application’ s message loop. This fniction is similar to 
TranslateAccelerator(), but it is customized to convert keystrokes into equivalent MDI messages. 

Windows provides two default message processing functions, DefFrameProc() and DefMDIChildProc(), to pro- 
cess messages for the frame and child windows. They take the place of DefWindowProc() that we have been using at 
the bottom of every WndProc() function to handle messages not processed by the application. Communication 
between the frame, client window, and child windows is handled via eleven specialized messages. Table 29-1 provides 
- a summary of each of these messages. The full message description for each is included in Chapter 9, Windows 
Messages. 


WM | MDIACTIVATE Used to activate child windows within a Multiple Document Interface (MDI) window. This is 


similar to a main window gaining the input focus. 

WM_MDICASCADE Arranges all of the child windows within the MDI client window in “cascade” format. 
WM_MDICREATE Creates an MDI child window. 
WM_MDIDESTROY Destroys (removes) an MDI child window. 
WM_MDIGETACTIVE ~ Obtains the handle of the currently active MDI child window. 
WM_MDIICONARRANGE Causes the MDI client window to arene all minimized MDI child windows at the bottom of the 

client area. , 
WN_MDIMAXIMIZE Causes an MD! child window to be maximized. 


WM_MDINEXT _ Activates the next MDI child window. - 


906 


29. MULTIPLE DOCUMENT INTERFACE (MD!) Vv 


WM_MDIRESTORE Restores an MDI child window to its previous size. 
WM_MDISETMENU Links anew menu to the MDI frame window. 
WM_MDITILE Causes an MDI client window to arrange all of its children in tile format. 507 


Table 29-1. MDI Message Summary. 


The example program in this chapter demonstrates the use of these messages. 


MDI Interface Bugs 


Although the MDI functions work well, there are a few bugs that you may run into. One is that the maximized child 
windows cannot be closed by double-clicking the child window’s close box (upper left corner). You can get around this 
problem by trapping WM_NCLBUTTONDBLCLK messages and checking if the active child window is maximized. The 
returned value from sending the WM_MDIGETACTIVE message will be 1 if the active child is maximized. If the child 
window is maximized and the mouse position is within the close box, you can close the child window directly. 
Another bug is that MDI applications tend to not release all of the Windows system resource memory when the 
MDI application terminates. The loss will only show up if you start and terminate the MID application a number of 
times. This small loss occurs even if you explicitly remove all child windows and their class definitions before the MDI 
application exits. The system memory area is a limited resource, with a maximum of 64K available. You can check this 
value from the program manager Help/About Program Maeeer menu item. Be sure to asp delete any resources 
(such as unattached menus) before the MDI application eagem 7 mete 
exits to minimize the drain on system resources. 


ontrols- "hile Win Windows 
MDI Example Program Coa ee| Rectangle ||| Rectangle |} 
| oa | ame | 


This example creates a simple MDI application. There 
are only two child window types. One displays a rect- 
angle, the other an ellipse. In both cases, the object 
changes size to fit within the child window borders. The 
MDI frame window supports two similar menus. If one of 
the children is active, the menu allows the color of the 
rectangle/ellipse to be changed. If the frame is active, Figure 29-3. MDI Example Program. 
the “MDI Controls” menu item replaces the color selec- 
tion item. “MDI Controls” demonstrates standard MDI features for tiling and cascading opened child windows, select- 
ing the next child window, and arranging iconized child windows. 

Figure 29-3 shows the example with five child windows created. The top three were tiled when the frame window 
was smaller. After enlarging the frame window, two more children were created and then minimized to icons. 

The resource file defines both menus, and the keyboard accelerators. The upper menu is used when the frame 
window is active. The lower menu applies when a child window is active. 


> GENERIC.RC Resource File for MDI 


/* generic.re */ 


Rectangle — Ellipse 


#include <windows.h> ° 
#include “generic.h" 


generic “ICON generic.ico 

Accel ACCELERATORS 

{ 
VK_F2, IDM_CASCADE, VIRTKEY 
VK_F3, IDM_ARRANGE, VIRTKEY 
VK_F4, IDM_TILE, VIRTKEY 
VK_F5, IDM_NEXT, VIRTKEY 

} 


FrameMenu MENU 
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BEGIN 


POPUP “&File” 


BEGIN 
MENUITEM “New &Rectangle", IDM_NEWRECT 
MENUITEM "New &ELLipse", IDM_NEWELIP 
MENUITEM SEPARATOR 
MENUITEM "“&CLlose Child", IOM_CLOSE 
MENUITEM "SExit Demo", IDM_QUIT 
END 
POPUP “&MDI Controls" 
BEGIN 
MENUITEM “Cascade Windows\tF2", IDM_CASCADE 
MENUITEM “Arrange Icons\tF3", IDM_ARRANGE 
MENUITEM “Tile Windows\tF4", IDM_TILE 
MENUITEM "Next Window\tF5", IDM_NEXT 
END : 
POPUP “&Child Windows” 
BEGIN | 
MENUITEM "Child Window List", IDM_MDILIST 
END : 
END 
ChildMenu MENU 
BEGIN . 
POPUP "SFile” 
BEGIN : 
MENUITEM “&Top Menu", IDM_TOP 
ae ae MENUITEM SEPARATOR | 
“~~ MENUITEM "“&@Close Child", IDM_CLOSE 
MENUITEM “GExit Demo", IDM_QUIT ee 
END : Tm ene ne oO 
POPUP “&Color" 
BEGIN 
MENUITEM “&Blue® IDM_BLUE 
MENUITEM "&Green" IDM_GREEN 
MENUITEM “&Red" IDM_RED . 
END. ; 
POPUP “&Child Windows" 
BEGIN 
“MENUITEM "Child Window List", IDM_MDILIST 
END ‘ 
END 


The header file defines all of the menu item ID numbers and see function declarations and the standard two 
global variables used in the examples in this book. bee _ 7 


> GENERIC.H Header File 


/* generic.h = */ 
tdefine /* menu item id values */ 
adefine 
#define 
adefine 
H#define 
#define 
&define 
#define 
adefine 
Sdefine 
Ndefine 
#define 
ddefine 


IDM_MDILIST 
IDM_QUIT 
IDM_NEWRECT 
IOM_NEWELIP 
IDM_CASCADE 
IDM_ARRANGE 
IDM_CLOSE 
IDM_TOP 
IDM_TILE 
IDM_RED 10 
IDM_BLUE 11 
1DM_GREEN «12 
1OM_NEXT 13 


WONAURWN = 


Adefine FIRST_CHILD 100 /* child window numbers above menu items */ 
“ft global variables */ 
ghIinstance ; = 


gszAppName £1] = “generic" ; 


int 
char 
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/* function prototypes */ 

long FAR PASCAL FrameWndProc CHWND, unsigned, WORD, LONG) ; 

tong FAR PASCAL ELipProc CHWND hChild, WORD wMhessage, WORD ‘Paraty 
LONG LParam) ; 

long FAR PASCAL RectProc CHWND hChild, WORD wMessage, WORD wParam, 
LONG lParam) ; 

void SetFrameMenu wei ddis 

void SetChildMenu (void) ; 

BOOL FAR PASCAL EAUNCh i Ldsenkhoy CHWND hWndChild, DWORD lParam) ; 


The program definition file shows the message processing functions for the frame window and the two types of 
child windows in the EXPORTS section. In addition, an enumeration function EnumChildDestroy() is listed. This 
function is used to delete all of the child windows before the MDI application exits. 


> GENERIC.DEF Definition File 


NAME GENERIC 
DESCRIPTION "generic mdi progran' 
EXETYPE WINDOWS 
stus "WINSTUB.EXE' 
CooE PRELOAD MOVEABLE DISCARDABLE 
DATA PRELOAD MOVEABLE MULTIPLE 
HEAPSIZE 1024 
STACKSIZE 8192 
EXPORTS FrameWndProc 

ElipProc 

RectProc 


EnumChildbestroy 
The NMAKE file is shown with the debug options set on. 
> GENERIC.NMAKE File 


ALL: generic.exe 


CFLAGS=—c -D LINT_ARGS -Zi -Od -Gsw -H2 
LFLAGS=/NOD /co 


generic.obj : generic,c generic.h — 
SC(CC) SCCFLAGS) generic.c 


generic.res: generic.re generic.ico 
re -r generic.rc 


generic.exe : generic.obj generic.def generic.res 
Link SCLFLAGS) generic, , ,Libw slibcew, generic 
re. generic.res 

The source code creates the frame window inside WinMain(). Creating the frame window causes 2 WM_CREATE 
message to be'sent to the frame window message processing function FrameWndProc(). The MDI client window is 
created while processing WM_CREATE. . 

The two new window classes, “rectangle” and “ellipse,” are also registered in the WM_CREATE section. The 
cbWndExira element of the window class definition is set to hold one global memory handle. This memory area will 
store the current color of the rectangle or ellipse for each window created. As the data is stored with each window, not 
with the class, changing the color of one MDI child does not change the color of any other similar child window. Note 
that the message loop in WinMain() has been modified to include both the TranslateMDISysAccel() and 
TranslateAccelerator() functions. 

The FrameWndProc() function sancnitales several of the MDI messages for controlling tiling and cascading 
child windows. Note that WM_COMMAND messages not processed by FrameWndProc() are sent on to any active 

child. 
_ The window functions for the two types of child windows are very similar. Both process WM_! COMMAND mes- 
sages, and change the rectangle or ellipse color if color menu item has been selected. Note that the memory area for 
storing the color of the rectangle/ellipse is allocated when the child window processes a WM_CREATE message. The 
handle is stored in the cbWndExtra element of the window's private data. The memory value is changed when the 
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window color value is altered. The memory value is retrieved before painting the rectangle or ellipse in the WM_PAINT 
section of these child window functions. 


© GENERIC.C Source Code 


/* generic.c generic windows application */ 


/**/ 

include <windows.h> . /* window's header file - always included “y 
#include "generic.h" /* the application® s Header file */ 

HWND ghWndFrame, ghWndClient : . 7* globals */ 


int PASCAL WinMain (HANDLE hInstance, HANDLE hPreviInstance, LPSTR LpszCmdLine, int nCmdShow) 
{ : ; 


HANDLE hAccel ; 

MSG MSg ; 

WNDCLASS wndclass ; 

HMENU hMenu ; 

ghInstance = hInstance ; /* store “hekancs handle as global var. */ 


hMenu = LoadMenu (hInstance, "“FrameMenu") ; 


if ('hPrevInstance) I create frame window class */ 
{ 
‘wndclass.style 
wndclass.lpfnWndProc 
wndclass.cbhClsExtra 
wndclass.cbWndExtra_ 
wndclass.hinstance 
wndclass.hicon 
wndclass.hCursor 
wndclass.hbrBackground 
/* aternative:, 
wndclass.lpszMenuNate 
wndclass.lpszClassName 


S_HREDRAW | CS_VREDRAW ; 
Famewnderes ; 


Cc 
F 
0 ; 
0; 
pinetanée ; 

LoadIcon (hInstance, Sszkpphanie? 7 
LoadCursor (NULL, IDC_ARROW) ; 
GetStockObject (WHITE_BRUSH) ; 

et backuround to COLOR_. APPWORKSPACE + 1, */ 
N 


i e-a 


‘MDI Frame" : 
/* register frame window class */ 
if (!RegisterClass (&wndclass)) 
‘ return FALSE ; 
} 


Spende rane = CreateWindow ¢ /* create the frame window */ 
“MDIFrame", /* class name */ 
“MDI Example", /* window name */ 
WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN, /* window style */ 
CW_USEDEFAULT, /* x position on screen */ 
CW_USEDEFAULT, /* y position on screen */ 
CW_USEDEFAULT, : /* width of window */ 
CW_USEDEFAULT, /* height of window */ 
NULL, | /* parent window handle */ 

' LoadMenu (ghInstance, “FrameMenu"), /* menu handle */ 

hInstance, ‘ /* instance handle */ 
NULL) ; /* tpstr Cnutl = not used) */ 


ShowWindow (ghWndFrame, nCmdShow) ; 

DrawMenuBar (ghWndFrame) ; : 
UpdateWindow (ghWndFrame) ; ! 
hAccel = LoadAccelerators (hInstance, "AcceL") ; 


\ 
/* the message loop */ 


while receiseasde Camsg, NULL, 0, 0)) 
{ 


if C!TranslateMDISysAccel (ghWndClient, @msg) && 
!TranslateAccelerator (ghWndFrame, hAccel, &msqg)): 
{ “S 


TranslateMessage (&msq) ; 
DispatchMessage (&msg) ; 
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} 
} 
return msg.wParam ; 
°} 


Long FAR PASCAL FrameWndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ : 


HWND hchild ; 
CLIENTCREATESTRUCT ccs ; 
MDICREATESTRUCT mcs ; 
WNDCLASS wndclass ; 

= HMENU hMenu ; 
FARPROC LpEnumFunc ; 


switch CiMessage) 
L 
case WM_CREATE: /* create MDI client window here */ . 
ccs. idFirstChild = FIRST_CHILD ; \ 
hMenu = LoadMenu (ghInstance, “FrameMenu") ; 
ccs.hWindowMenu = GetSubMenu (hMenu, 0) ; 
ghWndClient = CreateWindow ("MDICLIENT", NULL, 
WS_CHILD | WS_CLIPCHILDREN | WS_VISIBLE, 
0, 0, 0, 0, hWnd, NULL, ghInstance, (LPSTR) &ccs) ; 
SendMessage (hWnd, WM_MDISETMENU, O, 
MAKELONG (ccs.hWindowMenu, hMenu)) ; 


wndclass.style 
wndclass. lpfnWndProc 
wndclass.cbClsExtra 
wndclass.cbWndExtra 
wndclass.hinstance 
wndclass.hIcon 
wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
‘wndclass.lpszClassName 
RegisterClass (&wndclass 


wndclass.lLpfnWndProc = 
wndclass.lpszClassName = 
RegisterClass (&8wndclass) 
return (0) ; 
case WM_COMMAND: 
switch (wParam) 
{ 
case IDM_NEWRECT: 
mces.szClass 
mces.szTitle 
mcs .hOwner 
mcs.x 
mcs.y 
mcs .cx 
mcs.cy 
mcs.style 
mcs.lParam = 


et | | | 


~rbn bn tt bag 


CS_HREDRAW | 
ElipProc ; 

0; 

sizeof (GLOBALHANDLE) ; 
ghInstance ; : 
LoadIcon (NULL, IDI_APPLICATION) ; 
LoadCursor (NULL, IDC_CROSS) ; 
GetStockObject (WHITE_BRUSH) ; 
NULL ; 

"Ellipse" >; 

; /* reg ellipse wind class */ 


CS_VREDRAW ; 


RectProc ; 
“Rectangle” ; 
3 /*® reg rectangle wind class */ 


/* process menu items */ 


* make a new rectangle child window */ 


“Rectangle” ; 
“Rectangle” ; 
ghInstance ; 
CW_USEDEFAULT ; 
CW_USEDEFAULT ; 
CW_USEDEFAULT ; 
CW_USEDEFAULT ; 
0; 

NULL ; 


SendMessage (ghWndClient, WM_MDICREATE, O, 
CLONG) (LPMDICREATESTRUCT) &mcs) ;, 


break ; 
case IDM_NEWELIP: 
mes.szClass 
mes.szTitle 
mcs .hOwner 
mces.x 
mcs.y 
mcs.cx 
mcs.cy 
mes.style 


pnroeodbuna 


/* make a new ellipse child window */ 
"Ellipse" ; 
"Ellipse" ; 
ghinstance ; 
CWLUSEDEFAULT ; 
CW_USEDEFAULT ; 
CW_USEDEFAULT ; 
CW_USEDEFAULT ; 
Oo; 
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> . 
return (OL) ;. 


} 


mes.lParam = NULL ; 


SendMessage (ghWndClient, WM_MDICREATE, O, 
CLONG) CLPMDICREATESTRUCT) &mcs) ; 


break ; 
case IDM_CLOSE: 


hChild = LOWORD (SendMessage (ghtindtt tent, 


WM_MDIGETACTIVE, 0, OL)) ; 


SendMessage (ghWndClient, WM _MDIDESTROY, hChild, Ol) ; 


break ; 
case IDM_. ARRANGE: 


sendnessege (ghWndClient, WM_MDIICONARRANGE, O, OL): 


break ; 
case IDM_CASCADE: 


sendnesasde CghWndClient, WM_MDICASCADE, 0, OL) ; 


break ; 
case IDM_TILE: 


‘SendMessage CghWndClient, WM_NDITILE, 0, OL) ; 


break ; 
case IDM_NEXT: 


Senghessage (ghwndclient, WM_MDINEXT, 0, OL) ; 


break ; 


case IDM_QUIT:. /* destroy children, frame */- 


lpEnumFunc = MakeProcinstance (EnumChildDestroy, 


ghInstance) ; 


EnumChildWindows (ghwndclient, LpEnumFunc, OL) 


FreeProcInstance (lpEnumFunc) ; 
DestroyWindow (hWnd) ; 
break ; 


default: /* pass command to active child */ 
hChild = LOWORD (SendMessage (ghWndClient, 
, WM_MDIGETACTIVE, 0, OL)) >; 


if (IsWindow (hChitd)) 


¢ 


SendMessage (hChild, WM | COMMAND, wParam, 


lParam) ; 
break ; 
} 
break ; 
case WM_ DESTROY: /* free menu data betore exit */ 


hMenu = FindResource (ghInstance, ore see Merwe: , RT_MENU) 


hMenu = LoadResource (ghInstance, hMenu) ; 
if ChMenu) 
while (FreeResource ChMenu)) 


, 
hMenu = FindResource (ghiInstance, ee teMend’y RT_MENU)- 


hMenu = LoadResource (ghInstance, hMenu) ; 
“4f ChMenu) 
while (FreeResource ChMenu) > 


as 
PostQuitMessage (0) ; 
break ; 


default: 4* default windows-message-processing */ 
return DefFrameProc (hWnd, ghWndClient, iMessage, wParam, LParam) ; 


/* child window message processing procedure for ellipse windows */ 


ponaye FAR PASCAL ELipProc CHWND hchild, WORD wMessage, WORD wParam, LONG LParam) 


{ 
RECT rClient ; 
PAINTSTRUCT ps ; 
GLOBALHANDLE hfiem ; 
Bey LPSTR LpMem ; 
HBRUSH hBrush - 


switch (wMessage) 


{ 
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Case WM_CREATE: /* put default black color in window data */ 
hMem = GlobalAlloc (GHND, sizeof (DWORD)) ; 4 
SetWindowWord ChChitd, 0, hMem) ; /*save handle with window */ 
break >; ; ae .. 

case WM_MDIACTIVATE: 
if (wParam) , 

SetChildHenu () ; ; . ¢* gained input focus */ 


else : 

SetFrameMenu () ; : /* Lost input focus */ 
DrawMenuBar (ghWndFrame) ; ; : 
return (0) ; 


case WM_PAINT: 
GetClientRect Chchild, ErClient) ; 
-hMem = GetWindowWord (hChild, Q) ; /* color stored here */ 
LpMem = GlobalLock (hMem) >; — /* get handle to color */ 
BeginPaint (hChild, &ps).; me 
hBrush = CreateSolidBrush (RGB (*(lpMem + 1), *ClpMem + 2), 
~  *#ClpMem + 3))) ; . 
: GlobalUntock (hMem) ; 
: , SelectObject (ps. nde hBrush) ; 
are Ellipse (ps.hdc, 10, 10, rclient. right - 10, 
rClient -bottom - 10) ; 
DeleteObject ChBrush) ; 
EndPaint ChChild, ps). ; 
_. Return (0) ; 
case WM_COMMAND: > 
switch (wParam) 


case IDM_RED: /* change the cotor used to paint ellipse */ 
case IDM_BLUE: /* the color value is stored in global */ 
case IDM_GREEN: /* memory. Bem handle stored with wind */ 
hMem = GetWindowWord (hChild, 0) ; : 
lpMem = GlobalLock ChMem) ; 
*(LpMem + 1) = (wParam == 1D RED 2? 255 : QO) ; 
*(LpMem + 2) = (wParam == IDM_GREEN ? 255 : 0); 
*(lpMem + 3) = CwParam == IDM_BLUE 2 255 : 0) 
GlobalUnlock ChMem) ; 
InvalidateRect (hChild, NULL, TRUE) ; 
case IDM_TOP: 
SetFrameMenu () ; 
break ; 


return (0) ; 
case WH_ DESTROY: 
hem = GetWindowWord Chchild, 0); 
GlobatFree (hem) ; ; 
4 return (0) ; 
return DefMDIChildProc (hChild, wMessage, wParam, lParam) ; 


/* child window message processing procedure for rectange windows */ 


eon FAR PASCAL RectProc CHUND hChild, WORD wHessage, WORD wParam, LONG LParam) 


RECT "on  pClient ; 
PAINTSTRUCT - - ps; 
GLOBALHANDLE ~  hMem ; 
LPSTR lpMem ; 
HBRUSH . hBrush ; 


switch CuMessage) , 
case WH_CREATE: /* put default black color in window data */ 
hMem = GlobalAlloc (GHND, sizeof CDWORD)) ; 
SetWindowWord anghi te, O, hMem) >; ° je save handle with mindos e/ 
break ; ' Mine ; . 
case WH: | MDIACTIVATE: 
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if. (wParam) a Noe te 
\ SetChildMenu O; /* gained input focus */ 
else ; 2Yeag 
Séthrawenenu oO; /* Lost input focus */ 
DrawMenuBar (ghndFrame) ; 
return (0) ; amt 
case WM_PAINT: ; 
GetClientRect ChChild, erctient) ; 
hMem = GetWindowWord Chchild, 0) ; /* color stored here */ 
lpMem = GlobalLock (hMem) ; /* get handle to color #7]! 
BeginPaint (hChild, &ps) ; . f 
hBrush = CreateSolidBrush, CRGB (*(lLpMem +1), *C lL pMem + 2), 
*(ipMem + 392) 3 og 
GlobalUntock ChMem) ; : 
SelectObject oe hae: hBrush) ; 
Rectangle (ps.hdc, 10, 10, FGLientocdght - 10, 
rClient -bottom - 10) ; 
DeleteObject (hBrush) ; 
EndPaint (hChild, Bps) ; 
return (0) ; 
case WM_COMMAND: | 
switch (wParam) 


case IDM_RED: /* change the color used to paint rect. */ 
case IDM_BLUE: /* the color value is stored in global */ 
case IDM_GREEN: /* memory. Mem handle stored with wind */ 
hMem = GetWindowWord (hChild, 0) ; 
lpMem = GlobalLock (hMem) ; 
*(lLpMem + 1) = (wParam == IDM_RED ? 255 : 0) 
“«*ClpMem + 2) = (wParam == IDM_GREEN ? 255 : 0) ; 
*(LpMem + 3) = aparaw == JDM_BLUE ? 255 : 0) ; 
GlobalUnlock ChMem) ; ‘ 
ovat idacene ct: Chehild, NULL, TRUE); 
case IDM_TOP: 
SetFrameMenu () ; 
break ; 
_} 
return (0) ; 
case WM_.DESTROY: 
“hMem = SethindosWord ChChild, 0); 
GlobalFree SOBER? 
: return (0) ; 
oo Se 
“return DefMDIChildProc (hChild, wMessage, wParam, lParam) ; 


“Jo 
wit 
a 


void Set FrameMenu (void) /* put the frame menu at top */ <4 
{ free 

dtatic HMENU hMenu = NULL ; 

HMENU hSubMenu ; 

int nMenultems ; 


if C!hMenu) 
hMenu = LoadMenu (ghInstance, "FrameMenu"): ; 

nMenultems = GetMenultemCount (hMenu) ; 

hSubMenu = GetSubMenu (hMenu, nMenultems - 1) ; 

_ SendMessage (ghWndClient, WM_MDISETMENU, 0, 

MAKELONG ChMenu, hSubMenu)) ; 

‘DrawMenuBar (ghWndFrame) ; 

} 


void SetChildMenu (void) /* put the child window menu at top */ 


{ ; 
static HMENU  hMenu = NULL ; , 74 
HMENU hSubMenu ; 
int ~ nMenultems ; 


if (!hMenu). 
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hMenu = LoadMenu (ghInstance, “ChitdMenu") ; 
nMenultems = GetMenultemCount (hMenu) ; 
hSubMenu = GetSubMenu (hMenu, nMenultems = 1) 
SendMessage (ghWndClient, WM_MDISETMENU, O, 
MAKELONG ChMenu, hSubMenu)) ; 
DrawMenuBar (ghWndFrame) ; 
} 


BOOL FAR PASCAL EnumChildDestroy (HWND hWndChild, DWORD LParam) 
{ 


SendMessage (ghWndClient, WM_MDIDESTROY, hWndChild, OL) ; 
‘return (TRUE) ; / 


Because the example program uses two menus, only one of the menus is attached to the frame window when the 
program exits. This means that the menu data for the unattached menu will be left in memory after the application 
terminates unless it is explicitly removed. The logic in the processing of the WM_DESTROY message in Frame- 
WndProc() handles removal of the menu resource data. FreeResource() must be called as many times as Load- 
Resource() was called to actually remove the resource from memory. The EnumChildDestroy() function at the bottom 
of the listing demonstrates a simple technique for sending a message to all of the child windows. In this case, it is the 
WM_MDIDESTROY message. The same technique can be used to send any message, including user messages. 

-. This example shows two separate functions for processing rectangular and elliptical child windows. This ap- 
proach was used to demonstrate passing control to separate message processing functions, the most general case. 
These two functions are so similar that they could easily be combined into one function. The type of window (rect- 
angle or ellipse) would be stered with the color data in the memory block associated with each child window. When 
the child window received a WM_PAINT message, it would determine what shape to paint along with the color data. 


MDI Function Summary 
Table 29-2 summarizes the MDI support functions. 


DefFrameProc Provides default message processing for the window function of the frame widen in an MDI 


application. 

DefMDIChildProc Provides default message processing for the window function of a child window in an MDI 
application. 

TranslateMDISysAccel Provides default translation of Windows keyboard messages for MDI'applications. a 


Table 29-2. MDI Function Summary. 


MDI Function Descriptions 
This section contains the detailed descriptions of the MDI support functions. 


DerFRAMEPROC OWin2.0 Win3.0  mWin3.1 
Purpose Provides default message processing for the window function of the frame window in an MDI 
. (multiple document interface) application. 
Syntax “LONG DefFrameProc(HWND hWnd, HWND hWndMDIClient, WORD wis, WORD wParam, 
LONG lParam); é 
Description In an MDI application, the frame window is primarily responsible for maintaining the menu. All 


child windows share the same menu line. The default MDI behavior will add child window names, 
preceded by a number, to the menu line as the child windows are activated. DefFrameProc() is 
the equivalent of DefWindowProc(), except that DefFrameProc() provides specialized functions 
for an MDI frame window as the default. All messages that are not processed by the frame 
window’s message processing logic should be passed to DefFrameProc(). 
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Uses 
Returns 

See Also 
Parameters 
hWnd 
hWndMDIClient 
Msg 
wParam | 


Used at the bottom of the frame window message processing (window) function to bane mes- 
sages not explicitly processed by the program's logic. 


" LONG. This value is returned to Windows as the returned value from the frame window’ 8 message 


processing (window) function. 
DefMDIChildProc(), CreateWindow() 


HWND: The MDI frame nda handle. 


_ HWND: The MDI client window handle. The client window is normally created during ate: 


of the WM_CREATE message for the frame window. Client windows are created from the class 
MDICLIENT. 


WORD: The message ID value (such as WM -MOVE).1 This value is initially sent: from Windows to 
the frame window function. 


WORD: The 16-bit value passed with the message This value is ntl sent from Windows to the 
frame window function. 


DWORD: The 32-bit value passed with the message. This value is initially sent from Windows to 
the frame window function. 


Related Messages All messages that the MDI frame window message processing (window) function receives, but 


does not act on, are sent to DefFrameProc(). In addition, the following messages should be passed. © 
to DefFrameProc ( regardless of whether action is taken in the MDI frame window’s message 
processing function: WM_COMMAND, WM_MENUCHAR, WM _NEXTMENU, WM_ SET FOCUS, 


and WM _SIZE. 


The MDI example earlier in this chapter uses DefFrameProc() at the bottom’ of the MDI Rane 
message processing function, FrameWndProc(). 


DerMDICawpProc © fat 8S OWin2.0 wWin30. mWin3t 


Purpese Provides default message processing for the window function of a child window i in an n MDT (uk 
| tiple document interface) application. 
. Syntax LONG DefMDIChildProc(HWND hWnd, WORD wifsg, WORD wParam, LONG lParam), 
Description This function takes the place of DefWindowProc() fora child window message function in an MDI 
S55, window. The default processing notifies the MDI client window when a child i is created or closed, 
t and also does the normal chores for sizing the child window, i iconizing, etc. 
Uses Used within the child window function of an MDI application. - : 
Returns LONG. This value is returned to Windows as the returned value from the child message process- 
‘ing (window) function. 
See Also - DefFrameProc() 
Parameters anes 
hWnd HWND: The MDI child window handle. 
whsg WORD: The message ID value (such as WM_MOVE). This value is initially sent ‘froin Windows to 
the child window function. 
wParam WORD: The 16-bit value passed with the message. This value is initia sent from Windows to the 
child window function. 
iParam | -DWORD: The 32-bit value passed with the message. This value is initially sent from Windows nto 


--. the child window function. 


U 
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Related Messages The following Messages are actively processed by this function: WM_CHILDACTIVATE, WM_GET- 
MINMAXINFO, WM_MENUCHAR, WM_MOVE,WM_NEXTMENU, WM_SETFOCUS, WM_SIZE, 

_ and WM_SYSCOMMAND. 


Example Both the RectProc() and ElipProc() window functions in the MDI ois earlier in this chapter 
use this function. 
TRANSLATEMDISysAccEL OWin2.0 sWin30 gmWin3.l 
Purpose Provides defau!t translation of Windows keyboard messages for MDI applications. - 
~ Syntax _ BOOL TranslateMDISysAccel(HWND hWndClient, LPMSG IpMsq); 
Description This function is used within the MDI application's message loop to process system menu input for 


the MDI frame window. If the message is translated, the function returns 1. In this case, the 
message should not be passed on to TranslateMessage() and DispatchMessage(), as the trans- 
lated equivalent to the original message will be placed on the application’s message queue. 


Uses Used within an MDI application's message loop. 

Returns BOOL. TRUE if the message was processed, FALSE if not. 

Parameters 

hWndClient ——__. HWND: The MDI client window handle. Note that this is the client window, not the frame window 
handle. 


lpMsg _ LPMSG:. A pointer to an MSG data structure containing the Windows message. The message is 
assumed to have been retrieved from Windows with either GetMessage() or PeekMessage(). 
Related Messages All messages are passed through this function. 
Example The genera} structure for an MDI message loop is as follows: 
white CGetHessage C&amsg, NULL, O, 0)) /* the message loop */ 


if C!TranslateMDISysAccel ChWndClient, &msg) && 
!TranslateAccelerator (hWndFrame, hAccel, &msg)) 
{ \ 
TranslateMessage (&asg) ; 
DispatchHessage (&msg) ; 


This example shows both the MDI message translation and accelerator table translations 
being checked in the message loop. If the MDI application does not use keyboard accelerators, 
the TranslateAccelerator() function can be omitted. 
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Dynamic Data Exchange is a message protocol that allows Windows applications to exchange data. Using DDE is 
similar to using the clipboard. With the clipboard, the user is normally in charge of controlling the cut and paste 
- operations. With DDE, the application can control the flow of data in the background. DDE is ideal for problems such 
as displaying stock quotes as they change, or providing links between different types of applications. Microsoft Word 
for Windows and Excel support DDE links far updating spreadsheet values shown within a word processing document. | 
- DDE is implemented with nine Windows messages. Learning to use DDE in your applications is simply a matter of — 
learning how these nine messages work. You can register your own unique messages for data transmittal to exchange — 
data between two or more programs you are working on. By using the DDE messages defined in the DDE.H header file, 
your application will be able to exchange data with many other programs that use the DDE standard. 
Windows 3.1 includes an alternative method of implementing DDE viaa series of about 25 functions that reside i in 
a DLL library called DDEML.LIB. These functions provide a different programmer’s interface to DDE, but work on the 
same principles described in this chapter. DDE data exchange implemented with the DDEML functions iscompatible — 
with the conventional DDE implemented with Windows messages. The DDEML functions are not covered in this book. 


‘How DDE Data Is Exchanged 


Because DDE is a message-based system, the data must be transmitted with messages. Windows messages allow only . 
two parameter values, a WORD (wParam) and a DWORD (/Param). That is not enough rooin to transmit much 
information. To get around this limit, the [Param value is used to hold an indirect address to a block of memory. For 
short strings used to pass the names of data elements, /Param holds one or two global atom values. For larger amounts 
of data, amen holds the bapale of a global memory block allocated using GlobalAlloc() with the GMEM_DDESHARE 
option. 

Cfobal toms and DDESHARE aldbal memory blocks are used because they are the only two types of data that can 
be safely ted by two Separate applications. Trying to read a normal memory block allocated by another application 
risks the dreaded “Sharing Violation” error message, and/or termination of the program. Future releases of Windows 
are expected to have even more stringent safeguards against the use of another application’s data. : 

Keep in mind that there are two other ways to exchange data between applications. One is to use the clipboard. 

_The other is to read data maintained by a dynamic link library (DLL). 

The DDE protocol requires nine messages because there are several different situations that an application may 
need to address. One is that the receiving application may not be running. Applications that are not running will not 
get DDE data. Another problem is that the receiving application may be running, but not ready to receive the data. : 
Also, the receiving application may be able to read several different formats or types of DDE data, and it will need to 
decid@ahtich format to read, and which to reject. 

WaDDE conversation, the client is the application that starts the conversation. The server is the application that 
tesponds to the client. In most cases, the server will provide data to the client, but this does not have to be the case, 
as-we.will see’ in the first example in this chapter. To keep things simple, we will look at cases where only one DDE 

: ‘conyézsation i is going on at one time. An application can engage in several DDE conversations at once. This means that 
an‘application can be both a client and a server at the same time. 


% 
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Applications, Topics, and Item Identifiers 


Because a server may be able to send more than one type of data, DDE messages label data with character strings 
stored as global atoms. Atoms are used to transmit the name of the application and the name of the data item(s) 
requested. 

Data items are labeled with three levels of identifiers. When the DDE conversation is started, both the client and 
server must support the same “application” and “topic.” “Application” is normally the name of the server program, 
while “topic” refers to one of a number of DDE subjects that the program may exchange (such as plots, text, bitmaps, 
etc.). Limiting the conversation to a specific application and topic is important. Otherwise, all running applications 
that support DDE would respond to all messages. As soon as the DDE conversation is established, the specific Gate 
element requested is specified with the “item” name, 


Cold DDE Link 


The simplest DDE conversation, the cold link, is ideal for sending a packet of information on an infrequent basis, DDE 
conversations start when the client sends a WM_DDE_INITIATE message. This is the only DDE message that is sent 
with SendMessage(). The rest are posted with PostMessage(), placing the messages on the message queue of the 
receiving application. SendMessage() has the handy ability to transmit the same message to every running applica- 
tion on the system. 

The WM_DDE_INITIATE message uses the /Param parameter to encode the desired application name and topic 
name as global atoms. An application having the ability to respond to this type of data sends back a WM_DDE_ACK 
acknowledgement message, as shown in Table 30-1. Other applications running on the system plenore the 
WM_DDE_INITIATE message. 


Data Transmitted 


1) =WNM_DDE_INITIATE Client Server Application name, topic name {as atoms). 


2 WM_DDE_ACK Server Client Echoes application and topic names if server can supply data. Also 
provides window handle of server. 


Table 30-1. Initiation of a DDE Conversation. 


If the client gets a WM_DDE_ACK back, the DDE conversation has started. Now the client can ask for some data. 
If WM_DDE_ACK is not returned, the server application is probably not running. The client can attempt to start the 
server by calling WinExec(), or simply give up and display a warning message.’ 

Assuming a link was established, the client requests the data be transmitted by eae a WM_DDE_REQUEST 
message to the server. A handle to the memory block containing the data is sent back with a WM_DDE_DATA mes- 
sage. The client confirms the receipt of the data with a WM_DDE_ACK aetna as shown in Table 30-2. 


Data Transmitted 


3 WNM_DDE_REQUEST Client Server — The name of the data item mee? (as an aon and the clipboard 
: format to use for the data. 


-4 — WM_DDE_DATA | Server Client ‘Echoes the data item name (as an atom), and passes a handle toa 
global memory block containing the data. 


5 WM_DDE_ACK , Client Server Echoes the data item name (as an atom), and lets server know if the 
data was accepted. 


Table 30-2. A DDE Cold Link Data Transmission. ’ 


The actual data is passed within a global memory block allocated with GlobalAlloc(). The GMEM_DDESHARE 
option is used when allocating the memory block to allow the data to be passed without causing a memory error 
(“sharing violation”). 
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If the server cannot respond to the WM_DDE_REQUEST, the server transmits a WM_DDE_DATA message encod- 
ing a zero in one of the bit fields of the data (the fAck bit field). This is called a “negative” acknowledgment. If the 
server can send the requested data item, the bit field is set to one. This is called a “positive” acknowledgment. 

‘ The data item name is passed as a global atom with every message. This allows an application involved in several 
DDE conversations to keep track of which request is being processed. Additional WM_DDE_REQUEST messages can 
be sent foreach data item that the client would like to receive. When all of the data has been collected, the DDE 
‘conversation i is terminated, as shown in Table 30- 3. 


6 . WM DDE. TERMINATE “Cient Server The handle of the client window. 
7 WM_DDE_TERMINATE Server Client The handle of the server window. 
Table a Termination of a DDE Conversation. 


Hot! DDE Link 


“The cold link is fine for sending a packet of nA at one time, but it is inefficient if the client would like to receive data 
whenever the data changes. Examples of data that change periodically are links between communications programs 
and spreadsheets. The classic example is updating an Excel spreadsheet based on the latest stock quotes received 
over a modem. The hot link is initiated the same way as a cold link. When the conversation is established, the client 
sends the server a WM_DDE_ADVISE message. This lets the server know that the client would like the data sent every 
time the data changes. The transmittal of the WM_DDE_DATA messages. then goes on as needed, until either the 
server or the client terminates the conversation. 

Table 30-4 shows the message sequence. - 

To Da ee 


paisa late 


ae WM. | DDE | INTATE Client ‘Server — Application me ieie name oe ek 
2  WN_DDE_ACK Server Client Echoes application and topic names if server can supply data. Also 
: provides window handie of server. 


3 WM_DDE_ADVISE Client Server The name of the data item requested (as an ne the aiess format 
to use for the data, and the link type (hot). 


4 WN_DDE_DATA Server Client Echoes the data item name (as an atom), and passes a handle to a 
ory global memory block containing the data. 
5 WN_DDE_ACK Client Server — Echoes the data item name (as an atom), and lets server know if the 
(optional, depends on ae data was accepted. 
the fAckReq flag sent 
with WM_DDE_ADVISE). 
(Steps 4-5 continue as | 
_ the server's data changes.) 


6 WM_DDETERMINATE Client Server The handle of the client window. 
7 WM_DDE_TERMINATE Server Client The handle of the server window. 
"Table 50-4, Sequence of a Hot DDE Conversation. 


The client can temporarily stop updates from the server by posting a WM_DDE_! UNADVISE 1 message. This mes- 
sage does not terminate the een) but lets the server know that updates are not needed until a WM_DDE_AD- 


mae message is posted. 
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Warm DDE Link ~ 


~ The hot DDE link is ideal for intermittent transmittal of small amounts of data. For larger amounts of data, or feast 

transmissions, the client may not be able to deal with the data all of the time. The warm DDE link provides a compro- 

_ mise. The server notifies the client with a WM_DDE_DATA message when the data changes, but sends a NULL in 

place of the handle to the memory block containing the data. If the client is busy, it can ignore the message. If the 

client has time to read the data, it sends a WM_DDE_REQUEST message back to the server. The server then tranamits 

another WM_DDE_DATA message, this time including the handle to the data. i 
Table 30-5 shows the warm link message sequence. 


1  WN_DDE_ INMATE _ Glent Server Appicalion name, ete is sera 


2° WM_DDE_ACK Server Client Echoes application and topic names if server can supply data. Also 
provides window handle of server. 


3 WN_DDE_ADVISE Client Server — Thename of the data item requested (as an atom), the clipboard format 
to use for the data and the link type (warm). 


4 WMDDE_DATA — Server — Client Echoes the data item name (as an atom), and passes a NULL in place of 


the handle to a global memory block ‘containing the data. . 
‘§ WNM_DDE_ACK ~ Client Server — Echoes the data item name (as an ‘atom), and lets server know if the. 
(optional, depends on data was accepted. 
the fAckReq flag sent 
with WM_DDE_ADVISE). 
(Steps 4-5 continue as 
the server's data changes. ~ 


No data is transmitted until 
_ ~aWN_DDE_REQUEST is posted.) 


6 WM_DDE_REQUEST Client Server — Thename of the data item requested (as an atom), and the clipboard 


format to use for the data. ; 
7 WM_DDE_DATA Server Client Echoes the data item name (as an atom), and passes a handie tqa o- 
"4 . global memory block containing the data. 
8. WNM_DDE_ACK Client Server Echoes the data item name (as an atom), and lets server know if the 
~ (optional, depends on data was accepted. 
the fAckReq flag sent 
with WM_DDE_DATA). 
(The conversation continues 
with steps 4-5). 


(9 WMLDDETERMINATE Cient Server The handle of the clent window. 
10 WM_DDE_TERMINATE Server Client = The handle of the server window. 


Table 30-5. Sequence of a Warm DDE Conversation. 


In general, an application supporting DDE should support old, warm, and hot links. The data ad in global 
‘memory blocks uses a clipboard data format to structure the data. It is preferable to support the CF_TEXT clipboard‘ 
data format, as this is the most likely method of transmitting data. Other, more specialized data formats, can be 
supported in addition to CF_TEXT: CF_TEXT provides the ¢ common denominator for ovo of data between pro- 
oe written is different people. . 
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Generalized DDE Conversations 


If you are writing both the client and server application, you can control the names of the application, topics and 
items. The more general situation occurs when your application needs to be able to exchange data with a range of. 
applications, using topics and items which are not known. There are two types of support for generalized DDE conver- . 
sations. The first is the use of “wild card names” during the DDE connection step. (Using a wild card name is similar 
to using the ‘“*” notation in DOS when doing a directory search.) If the client specifies NULL in place of the applica- 
tion name atom or topic name atom, all running DDE servers will respond. The client can then look over the applica- 
tion and/or topic names that come back (via WM_DDE_ACK messages) and choose which ones are appropriate to 
establish DDE links. 

The other convention used for generalized DDE conversations is support of the “System” topic. Supporting the 
system topic is not required, out strongly recommended for any DDE server application. The idea is that all DDE 
applications support this topic name and provide standard information items to potential clients. The clients canthen | 
use the information to narrow the choice of which data to exchange. Table 30-6 shows the recommended “System” 
topic data items that a server should support. In all cases, the data is transmitted as character strings (CF_TEXT 
clipboard format). Multiple items in the si are Seuaried by tab characters. 


~-|ttem:Name;. Data Transmitted’ 


Sysitems A list of the items that the see supports as a of the system a 


Topics A list of the items that the application can support at this time. This may change, depending on what activity 
the application is doing. 


ReturnMessage _— Data in support of the last WM_DDE_ACK message. This is a way for the server to transmit additional data. 


Status ‘The application receiving a WM_DDE_REQUEST message for this item should respond with a 
WM_ DDE_DATA message containing either “Busy” or “Ready.” 


Formats A list of the clipboard formats that the server supports. The server should list them in the order of 
preference. The first format should be the format that retains the maximum amount of information. 


Table 30-6. “System” Topic Items. 


The second example, Listing 30-2, uses Microsoft Excel’s support of the System topic to obtain information from 
¢Excel..One thing to keep in mind with generalized DDE conversations is that a single initiation of a DDE link using 
wild cards will result in a large number of messages being transmitted. Processing these messages takes Hime and can 


significantly slow down system’ performance. ‘ 


- 


Other DDE Data Transmission Messages 

In the descriptions of the three types of links (cold, hot, warm), the data was always transmitted with a 
WM_DDE_DATA message. This is the general method of sending any type of data. There is an alternative if the data 
transmitted is a series of one or more character string commands. This is appropriate when one application will 
control another application’s behavior. A good example of this is control of the Windows Program Manager applica- 
tion. The Program Manager responds to five different DDE commands. They are described in Section 22-20 of the 
Windows SDK manual and are summarized in Table 30-7. 


[CreateGroup(New Group)} : Creates a new program group called “New Group” in the Program Manager window. - 

[Additem(FILENAME.EXT, MyFile)}. Adds the application FILENAME.EXT to the group, and names the application icon 
“MyFile.” 

[DeleteGroup(Old Group}] Deletes a program group called “Old Group” in 2. Manager window. 
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{ShowGroup(New Group, 1)] Displays a group called “New Group.. The second value is a code: 1=Show normal, 
2=Show iconic, 3=Show maximized, 4=Show last size, 5=Activate, show current size, 
6=Show minimized, 7=Minimize, no change in active group, 8=Show current size, no 
change in active group. 


[ExitProgMan(1)} Exits the Program Manager. O=Exit without saving, 1=Save state. 
Table 30-7. Windows Program Manager DDE Commands. 


To use these commands, an application establishes a DDE conversation with the Windows Program Manager 
application, In this case, the application name and topic are both “PROGMAN.” The commands are enclosed in square 
brackets and sent with a WM_DDE_EXECUTE message. The first example program (Listing 30- 1) demonstrates cre- 
ating a program group using DDE messages. 

_ -The other message for sending data is WM_DDE_POKE. It is used when a DDE conversation is in either a warm or 
hot tink; but when data needs to be transmitted without a prompting WM_DDE_DATA. message from the client to the 
server. It can: be thought of as an “I know you did not ask for this, but here it is anyway” message. 


Adding a New Group to the Program Manager . 

This example, see Listing 30-1, creates a new program group in the Windows Program Manager window, and adds the 
WINFILE.EXE program to the group. It is typical of a cold link DDE session that would take place in an install pro- 
gram. Figure 30-1 shows how the Program Manager window will appear after this example program is executed. 

The DDE conversation is managed by a hidden window. The hidden window is convenient, as it allows DDE 
messages to be sent to the “window” without complicating the WndProc() function for the application’s main window. 
The “sender” window class is created in WndProc() when the WM_CREATE message is processed. The “sendér” 
window class has its own window message processing 


function SenderProc(), shown at the end of the listing. peat st ia Prodram | Manager’ 

SenderProc() must be included in the EXPORTS section 

of the program’s .DEF definition file. A function proto- TT IP LSet bey 
die ees ee ec eae 


type should also be added to the program's header file. 

The application starts the conversation with Pro- 
gram Manager when SenderProc() processes the 
WM_CREATE message. The WM_DDE_EXECUTE mes- 
sages are not sent until SenderProc() receives a 
WM_USER + 1 message from the application's main win- 
dow. This message is sent when the user clicks the "Do 
It!” menu item, aot son 

Two WM_DDE_EXECUTE messages are sent to the wean, © PoP aes aise 
Program Manager. The first one contains a command . 
string with both the CreateGroupQ) and ShowGroupQ) Figure 30-1. Adding a Group to the Program Manager. 
commands, The second message transmits Additem(). % 
The two messages could have been combined into a single longer message. 

WM_DDE_ACK messages received after the initial WM_DDE_INITIATE message, and after the two 
WM_DDE_EXECUTE messages, are posted. SenderProc() uses Boolean values to take a shortcut when keeping track 
of which ACK is expected. This is fine for a simple DDE application, bul. becomes complex if several DDE conversa- 
tions are happening at the same time. In those cases, use the item name (stored as an atom) to determine which DDE 
message is being processed. 


Y Listing 30-1. Creating a Program Group Inside the Program Manager 
/* generic.c dde example - creates group in program manager */ 


Hinclude <windows.h> ; : 
Hinclude <dde.h> /* note inclusion of DDE.H */ 


* 923- 


WINDOWS API BIBLE 
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include "generic.h" 


“4nt PASCAL WinMain CHANDLE hInstance, HANDLE hPreviInstance, LPSTR LpszCmdLine, int nCmdShow) 
£ ; : i. . 


HWND hWnd ; 
MSG msg ; 
WNDCLASS wndclass ; 


. 
ta 


ghInstance = hInstance 

if C!hPrevinstance) 

{ : 
wndclass.style 
wndclass.tpfnWndProc 
wndclass.cbClsExtra 
wndclass.cbWndExtra 
wndclass.hInstance - 
wndclass.hIcon 
wndclass.hCursor 
wndclass.hbrBackground 
wndclass.lpszMenuName 
wndclass.tpszClassName 
if C!RegisterClass (&wndclass)) 

return FALSE ; ; 

} 


= CreateWindow (¢ 
aszAppName, 
gszAppName, 
WS_OVERLAPPEDWINDOW, 
CW_USEDEFAULT, 
CW_USEDEFAULT, 
CW_USEDEFAULT, 
CW_USEDEFAULT, 
“NULL, 
NULL, : 
hInstance, 

NULL) ; 

ShowWindow ChWnd, nCmdShow) ; 

UpdateWindow ChwWnd) ; 


hWnd 


white (GetNessage (&msg, NULL, 0,.0)) 
{ i : 


TranslateMessage (&msg) ; 
DispatchMessage (&msg) ; 
} 
return msg.wParam ; 
} 


/* store instance handle as global var. */ 


CS_HREDRAW | CS_VREDRAW ; 
WndProc ; 

0; 

0; 

hInstance ; 

LoadiIcon ChInstance, gszAppName) ; 
LoadCursor (NULL, IDC_ARROW) ;- 
GetStockObject (WHITE_BRUSH) ; 
gszAppNane ; 

gszAppName ; 


create the program's window here */ 
class name */ 

Window name */ 

window style */ 

x position on screen */ 
y position on screen */ 
width of window */ 
height of window */ | 
parent window handle (null = none) */ 
menu handle (null = use class menu) */ 
instance handle */ 

Lpstr (null = not used) */ 


send first WM_PAINT message */ 


/* the message. loop */ 


long FAR PASCAL WndProc CHWND hwnd, unsigned iMessage, WORD wParam, LONG LParam) 
: 


WNDCLASS 
static 


wndclass ; 
hSender 


a 


HWND 
suitch CiMessage) 
{ 


case WM_CREATE: 
wndclass.style 
undclass.lpfniindProc 
wndclass.cbClsExtra 
wndclass.cbWndExtra 
wndclass.hInstance 
wndclass.hIcon 
wndclass.hCursor. 
wundclass.hbrBackground 
wndclass.lpszMenuName 
undclass.lpszClassName 
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/* create a sever window class */ 


enderProc ; 


we Ne Ne 


0 
=) 
0 
0. 


ghInstance ; 


NULL 
NULL 
NULL 
NULL 

“sender” ; 


wa We Ne Ve 
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/* create a hidden sender window */ 
~ RegisterClass C&undclass) ; 
aa : 2 hSender = CreateWindow (ise ndents NULL, WS_CHILD, 0, 0, 0, 0, 
: : hWnd, NULL, ghInstance, NULL) ; 
if (!hSender) . 
MessageBox (hWnd, "Could not create DDE sender window.", 
“Error Message", MB_OK) ; 


break ; 
case WM_COMMAND: /* process menu items */ 
switch (wParam) : 
{ = 
case IDM_DOIT: _ /* tell sender to make a group */ 
PostMessage (hSender, WH_USER + 1, 0, QL) ; 
break ; 


case IDM_QUIT: 
Destnoy¥sndow Chiind) ; 
break ; ; 
} 
break ; 
case WM_DESTROY: 
PostQuitMessage (0) ; 
break ; 
default: . : 
return DefWindowProc (hind, iMessage, wParam, lParam) ; 
} * 
return (OL) ; , 
? : o 7 
/* window procedure for the hidden DDE sender window */ 


long FAR PASCAL SenderProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
4 oe . . : 


ATOM aApplication, aTopic ; 

static HWND hProgMgr = NULL ; 

HANDLE hMem1, hMem2 ; 

LPSTR lpHenm ; 

char cBuft CI] = . 

: . "CCreateGroup(New Group) I1[ShowGroup(Neu ee 7 
char cBuf2 CJ] = "NCAddItem(WINFILE.EXE Win File)]" ; 
static BOOL bInit = FALSE, bExec = FALSE ; 


switch (iMessage) 
s 


case WMH_CREATE: /* initiate dde conversation with ‘prog man */ 
aApplication = GlobalAddAtom (“PROGHAN") ; 
aTopic = GtobalAddAtom ("PROGMAN") ; ‘ 
bInit = TRUE ; : 
SendMessage G —1, WM_DDE_INITIATE, hwnd, 
MAKELONG CaApplication, aTopic)) ; 
GlobalDeteteAtom CaApplication) i: 
GlobalDeleteAtom CaTopic) ; 


break ; 
case WH_DDE_ACK: : 
if (bInit) ‘ .-/* ACK from a WM_DDE_INITIATE */ 
{ “ 
bInit = FALSE ; 
Slabalbelotaaton CLOWORD (LParam)) ; 
GlobalDeleteAtom CHIWORD (lParam)) ; 
if CiCtParam & 0x8000)) /* if ACK is negative */ - 
PostNessage (wParam, WH_DDE TERMINATE, hind, OL); 
else 
hProgNgr = wParam : /* save progran mgr handte fo 
) 5 4 
else if (bExec) /* ACK érot a WM_DDE_| EXECUTE. re 
{ ; 
bExec = FALSE ;_. , — 
if. CHIWORD (Param)) . 
GlobalFree (HIWORD (lLParam)) ; aa 
PostMessage (wParam, uN_ODE_ TERMINATE, hwnd, OL), 
} ee oa ; va 
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break ; . 
case (WM_USER ; aie /* message from WndProc() ~- make group */ 
ns if (hProgMgr) arse 
_~ E { 
bExec = TRUE ; 
hMem1 = GlobalAlloc (GMEM_ DDESHARE | GMEM = NOVERBLE ys 
sizeof (cBuf1) + ); 
lpMem = GlobalLock (hMem1) ; 
Lstrcpy (lpMem, (LPSTR) cBuf1) ; 
GlobalUnlock (hMem1) ; /* send first command string */ 
PostMessage (hProgMgr, WM_DDE_EXECUTE, hWnd, 
MAKELONG (0, hMem1)) ; 
hMem2 = GtobalAlloc (GMEM_DDESHARE | GMEM_MOVEABLE, 
sizeof (cBuf2) + 1) ; 
LpMem = GlobalLock (hMem2) ; 
lstrcepy (lpMem, (LPSTR) cBuf2) ; 
GlobalUnlock (hMem2) ; /* send second command aera */ 
PostMessage (hProgMgr, WM_DDE_EXECUTE, hWnd, 
MAKELONG (0, hMem2)) ; 
} 
break ; 


default: - 

return: DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} . Py 
return (COL) ; 


Obtaining File Names from Microsoft Excel 


In this example, the application establishes a DDE link with Microsoft Excel and obtains the current open file names. 
This is typical of the client side of a cold link DDE session. When executed, this application will display the names of 
the currently active files, as shown in Figure 30-2. . 

The DDE abilities of Excel are documented in the Excel user’s manual. Excel supports a broad range of DDE links, 
including cold, warm, and hot data links. This example Gbtains the file names by posting a WM_ DDE REQUEST for 
the “System” topic and the item “Topics.” Excel responds: 
with a WM_DDE_DATA message containing the file 
names in the clipboard format CF_TEXT. This text. data 
is saved in a global variable gcGlobTeatBuf]], so that the : 
application’s window can display the string. In addition, PC MANaGWAERCELWGRIRSTCOMnU aS Sheet! System 
the topic atom is retrieved and stored in the global vari- 
able gcGlobTopicBuf[]. This string is also displayed at = Figure 30-2. Example DDE Session Obtaining Data 
the top of the application’s window, primarily todemon- —_ from Microsoft Excel. 
strate manipulating global atoms. 

The top part of the listing including the WinMain() function is not repeated here, as it is identical to the previous 
listing. SenderProc() must be included in the EXPORTS section of the program’s .DEF definition file. A function 
prototype should also be added to the program’s header file. 

Note the interplay of USER messages being sent between the application’s main window and the sender window. 
Normally, the USER messages would be given names in the application's header file, such as 


excelred :: 


Do lt! Quit 


#define SENDDDEREQ WM_USER + 1 
In the example in Listing 30-2, the more direct WM_USER + n notation is used for clarity. 


> Listing 30-2. DDE Data from Microsoft Excel 


HWND | ghWndVisible ; /* shapes */ 
char gcGlobTextBuf (128) ; 
char gcGlobTopicBuf C1287, ; 


long FAR PASCAL WndProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG LParam) 
{ 
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WNDCLASS wndclass ; 
static HWND hSender ; 
PAINTSTRUCT ps ; 


‘switch (iMessage) 
of /* create a sever window class */ 
case WM_CREATE: 
ghWndVisible = hWnd ; 


wndclass.style =0; 
wndclass.lpfnwWndProc = SenderProc ; 
wndclass.cbClsExtra =0O; 
wndclass.cbWndExtra =0; 
wndclass.hInstance = ghInstance ; 
; , wndclass.hlIcon = NULL ; 
ui ' wndclass.hCursor = NULL ; 
: wndclass.hbrBackground = NULL ; 
wndclass.LpszMenuName = NULL : 
wndclass. [psc chesanene = “sender” ; 


ce create a hidden DDE ander window */ 
RegisterClass (Rundélesa) = 
hSender = CreateWindow C'sender"; NULL, WS_CHILD, 0, 0, O, O, 
hWnd, NULL, ghInstance, NULL) ; 
if ('hSender) . 
MessageBox (hWnd, "Could not create DOE sender window.", 
“Error Message", MB_OK) ; 


break ; 
case WM_COMMAND: /* process menu items */ 

switch (wParam) 

{ Py vee | 

case IDM_DOIT: /* tell dde wind to get data from excel */ 
PostMessage (hSender, WM_USER + 1, 0, OL) ; 
break ; 

case IDM_QUIT: /* tell dde wind to terminate dde */ 


PostMessage (hSender, WM_USER + 2, 0, OL) ; 
DestroyWindow (hWnd) ; 


break ; 
} 
break ; 
case WM_USER + 3: /* message from'dde wind - data ready */ 
InvalidateRect (hWnd, NULL, TRUE) ; 
break ; 


case WM_PAINT: 
BeginPaint (hWnd, &ps) ; 
TextOut (ps.hdc, 0, 0, gcGlobTopicBuf, 
lstrlen (gcGlobTopicBuf)) ; 
TextOut (ps.hdc, 0, 20, gcGlobTextBuf, 
Lstrlen (geGlobTextBuf)) ; 
endPaing ChWnd, &ps) ; 
break ; 
case WM__ DESTROY: 
Postaui tMessage, «O) ; 
break ; 
default: 
return DefWindowProc (hWnd, iMessage, wParam, lParam) ; 
} 
return (OL) ; 


Long FAR PASCAL SenderProc CHWND hWnd, unsigned iMessage, WORD wParam, LONG lParam) 
{ . 
ATOM. aApplication, aTopic, altem ; 


static HWND hExcelWnd = NULL : 
static BOOL bInit = FALSE ; 
DDEDATA FAR *LpDDEData ; 


switch CiMessage) 
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case WA_CREATE: 7 /* start dde conversation */ 
- aApplication = GlobalAddAtom ("Excel") ; 
aTopic = GlobatAddAtom ("System") ;-. 
bInit = TRUE ; 
SendMessage (- 1, WM_DDE_INITIATE, hWnd, 
v MAKELONG CaApplication, atopie)) ; 
GlobalLDeleteAtom (aApplication) ; 
GlobalDeleteAtom CaTopic) ; 
break ; 
case WM_DDE ACK: : 
if (bInit) /* ACK from a WH_DDE_INITIATE */ 
{ - 
bInit = FALSE ; 
GlobalDeleteAtom CLOWORD (LParam)) ; 
GlobalDeteteAtom CHIWORD (LParam)) ; 4) 
if (!CtParam & 0x8000)) /* if ACK is negative */ ; 
PostMessage (wParam, WM_DDE_TERMINATE,. hWnd, OL) ; 
else : . 
hExcelWnd = wParam ; /* save excel handle */ 
} : cr 
else * /* another ACK */ 
GlobalDeleteAtom CHIWORD (LParam)) ; 
break ; 
case WM_ODE_ DATA: /* got data back from excel */ 
/* save atom contents in buf */ 
GlobalGetAtomName CHIWORD (LParam), gcGlobTopicBuf, 128) ; 
; /* Lock the memory buffer */ . 
LpDDEData = CoOEUATA FAR *) GlobalLock (LOWORD (LParam)) ; 
a /* excel wants ACK 2? */ 
iif (ippdedata->fackkeq) ; 
PostMessage (hExcelWnd, WM_DDE_ACK, hWnd, 
MAKELONG (0x8000, HIWORD (LParam))) ; 
else ‘ * 
GlobalDeleteAtom CHIWORD (LParam)) ; . 
‘ -/* save the data if ‘tn CF_TEXT format */ 
if (lLpDDEData->cfFormat == CF_TEXT) 
{ 


Lstrcepy (gcGlobTextBuf, LpDDEData=>Vatue) ; 
/* tetl visible wind. data 4s ready, a] 
PostMessage (ghWndVisible, WM_USER + 3, 0, OL) ; eis 
? 
if (lpDDEData->fRelease) /* excel wants.cleanup ? */ 
GlobalFree (LOWORD (LParam)) ; 
else _— : 
: GlobalUnlock CLOWORD (LParam)) ; 
break ; a 
case (WM_USER ‘ : iP eee /* message from host - talk to Excel */ . 
if: ChExcelWnd) ms 
{ 
altem = GlobalAddAtom ("Topics") ‘; 
: PostHessage (hExcelWnd, WM_DDE_REQUEST, hWnd, 
~ MAKELONG (CF_TEXT, altem)) ; 
} 


break ; 
case CWM_USER + 2): /* message from host — quit dde */ 
PostMessage (hExcelWnd, WMH_DDE_TERMINATE, hWnd, OL) ; 


break ; 

default: 

ae return DefWindowProc ChWnd, iMessage, wParam, lParam) ; 
“return (OL) =. 2 a og 


928 


| 30. DYNAMIC DATA EXCHANGE (DDE) ¥ 


DDE Message Summary 


Table 30-8 summarizes the DDE messages. The detailed nen descriptions are in the next section. 


3 ~ os: Deseription ” a Ou ae. 

WM_DDE_ACK Notifies an application that another DDE. message was received. 

WM_DDE_ADVISE The client application sends this message to the server to inform the server that the client would 
like to receive-updated data any time the data changes. 

WM_DDE_DATA Sends data to the client application, or notifies the client that the data has changed in a warm 
link. : 

WM_DDE_EXECUTE Sends one or more command strings to the client application. 

WM_DDE_INITIATE Starts a DDE conversation. 

WM_DDE_POKE This message is posted by the client application, sending unsolicited data to the server. 

WM_DDE_REQUEST Posted by the client application to prompt transmittal of a data item from the server. 

WM_DDE_TERMINATE Stops a DDE conversation. | 


WM_DDE_UNADVISE - —_—_ Sent by the client application to stop updates of a particular item in a warm or hot link, 
Table 30-8. DDE Message Summary. . 


DDE Message Descriptions 


This section contains the detailed descriptions of the DDE messages. 
These messages are defined in the DDE.H header file that comes with the software development kit. 


WM_DDE_ACK @Win2.0 m@Win3.0 Wind) | 


_ Purpose Notifies an application that another DDE message was received. 
Syntax PostMessage (HWND hWnd, WM_DDE_ACK, WORD wParam, DWORD [Param); 


Discussion This message is posted in response te receipt of a WM_DDE_INITIATE, WM_DDE_EXECUTE, 
- WM_DDE_DATA, WM_DDE_ADVISE, WM_DDE_UNADVISE, or WM_DDE_POKE message. In 
some cases, WM_DDE_ACK is also posted in response to a WM_DDE_REQUEST message. (See 
that message description for details.) The response code with the WM_DDE_ACK message can 
be either positive or negative. If the fAck element (most significant bit) of the DDEACK data 
structure is zero, the response is negative. If fAck is one, the response is positive. 


Parameters . . ; . Be 

hWnd 7 HWND: The window handle of the window to receive the message. 

wParam WORD: The window handle of the window that sent the message. 

lParam DWORD: The meaning of /Param depends on which message the application is responding to. 


Responding to WM_DDE_INITIATE: The low-order word of [Param should be a global atom 
that contains the name of the replying application. The high-order word of [Param should con- 
tain a global atom containing the data topic. If the topic sent with WM_DDE_INITIATE is NULL, 
a WM_DDE_ACK should be sent back for every topic supported. 

Responding to WM_DDE_EXECUTE: The low-order word of [Param should contain a bit flag 
as specified in Table 30-9. The high-order word should contain a global memory handle contain- 
ing the command string. See WM_DDE_EXECUTE for details on the command string. 

Responding to all other DDE messages: The low-order word of [Param shouid contain a bit 
flag as specified in Table 30-9. The high-order word should contain a global atom contain the data 
item for which the response is sent. ; 
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“15--- fAck - ¢ a aaa accepted, 0 =Request not accepted. 
a Ve {Busy So Rie ede Busy. This only has meaning if fAck is Ze10. The bus) y flag should be set if the Sacsict 
- cannot respond immediately. 
13-8 reserved Reserved for Microsoft use. 


7-0 bAppRetumCode Reserved for application-specific return codes. 


Table 30-9. lParam Low-Order Word Flags for WM_DDE_ACK. 


These values correspond to the elements of the DDEACK data structure. This structure contains 
the bit fields, and is defined in DDE.H as follows: . : 


typedef struct € 


unsigned. bAppReturnCode: 8, 
: - reserved:6, 
a fBusy:1, 
_ :  fAck:1; 
"> DDEACK Oral oe hag ; 
Posting __ PostMessage() should be used to send WM_DDE_ACK. The only exception is when responding to’ 


a WM_DDE_INITIATE message. Then use SendMessage(). When responding to a message that 

contains a global atom, the application can reuse the atom received in responding, or it can’ 

delete the atom received, and then create and return a new atom. 

When responding to a ‘WM_DDE_EXECUTE message, the application should reuse the 

~ hCommands global memory object. This basically echoes the commands sent to the sender. The 

sender is responsible for deleting the hCommands object. Once a WM_DDE_TERMINATE mes- — 
“ sage is sent, the application should not acknowledge other messages from. the application that 

sent the WM_DDE_TERMINATE. i 


Receiving “An application expects to receive'a WM_DDE_ACK after sending data to another application. 
; ses osc When the ACK is received, the application knows that the other application has received the 
‘ ¥: data,'so it is safe to delete global atoms and memory areas containing the data that was sent. The 
-’: data should be deleted from memory even if the ACK was ence meaning that the other appli- 
eauion cous not use the aol 


WM_DDE “ADVISE. erie S ae ee eWin20 m Win 3.0 ma Win 3.1 


Purpose The client application sends this message to the server to inform the server that the client t would. 
like to receive updated data any time the data changes. . 

Syntax PostMessage (HWND hWnd, WM _ DDE ADVISE, WORD wParam, DWORD lParam); 

Discussion : nae This message is used to set up both hot and warin DDE links. Hot links involve transmission of the 


‘s data every time the data changes. ‘Warm links simply notify the client when the data has changed. 
The client then’ uses WM_ _DDE REQUEST to request the data. 


Parameters 


hWnd ~... HWND: The window handle of the window to receive the message. 
wParam’ ..WORD:. The window handle of the window sending the message. 
lParam ..' » \ DWORD: The high-order word (called a/tem) contains a global atom containing the name of the 


data item being requested. The low-order word (called Options) contains a handle to a global 
* memory block containing'a DDEADVISE data structure. This structure contains bit fields de- 
scribed i in Table 30-10. The DDEADVISE structure i is defined in DDE. H as piollows: 
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typedef struct { 


unsigned reserved:14, /* bits 0-13 reserved */ 
fDeferUpd:1, ‘/* warm Link request */ 
fAckReq:1; . /* ACK requested ? */ 

int cfFormat; /* clipboard format */ 


} DDEADVISE; 


hy Meaning,” 


15 fAckReq 


14 fDeferUpd 


13-0 reserved 


1=Server eneses to send WM_DDE_| DATA with the » okPeg bi bit set to 1.0 0: pone 
requested to send WM_DDE_DATA with the fAckReq bit set to 0. This inhibits sending the ACK 
messages, speeding data transfer 

1=Server is requested to send WM_DDE_DATA with hData set to NULL. This starts a warm link, 
where data is not transferred until the client sends a WM_DDE_REQUEST message. 0=Server is 
requested to send data with each WM_DDE_DATA message. 


Reserved for Microsoft use. 


Table 30-10. lParam Low-Order Word Flags for WM_DDE_ADVISE. 


cfFormat is the clipboard format used to transmit the data. This can be either a standard 
clipboard format, or a special format created with RegisterClipboardFormat(). If an application 
uses more than one clipboard format, it can post multiple WM_ DDE_ADVISE messages for sepa- 
rate topics and items. 


Posting Use PostMessage(), not SendMessage(), to transmit this message to another application. Be sure 
that the global memory object pointed to by the low-order word of [Param is allocated with 
GlobalAlloc() using the GMEM_DDE_SHARE option. This memory block should be deleted if the 

server responds with a WM_DDE_ACK message. 

Receiving Always respond to this message by posting a WM_DDE_ACK message. If responding positively, 
delete the hOptions global memory block containing the DDEADVISE structure. If responding 
negatively, do not delete the hOptions memory block, as the sender will delete it when it receives 
the negative WM_DDE_ACK. The a/iem global atom can either be reused, or deleted and a new 
item created in its place. 

WM_DDE_DATA gg Win2.0) m@Win3.0 gl Win3.1 

Purpose | Sends data to the client cmiarasie or notifies the client that the data has changed in a warm 

link. 

Syntax PostMessage (HWND hWnd, WM_DDE_DATA, WORD wParam, DWORD /Paraim); 

Discussion This message transfers data from the server to the client i ina DDE link. If a warm link has been 
established, this message simply informs the client that new data is available. It is up to the 

client to request the data with a WM_DDE_REQUEST message. 

Parameters \ 

hWnd HWND: The windew handle of the window to receive the message. 

wParam WORD: The window handle of the window sending the message. 

lParam — DWORD: The high-order word (called altem) contains a global atom containing the name of the . 


data item being sent. 
The low-order word (called Options) contains a handle to a dlobal memory block contain- 


.ing a DDEDATA data structure. This structure contains bit fields, which are described i in Table 


30-11. The DDEDATA dtructure i is defined in DDE.H as follows: 
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typedef struct { 


unsigned unused:12, 
fResponse:1,  /* 1 = got REQUEST, 0 = got ADVISE */ 
fRelease:1, §/* 1 = client frees data */ 
reserved:1, : 
fAckReq:1; /* 1 = expect ACK back */ 

int cfformat; _/* clipboard format */ 

BYTE Vatuel1]; /* can be more than one element */ 

} DDEDATA; 


15 fAckReq 


13 fDeferUpd 


1=Client is expected to send a WM | DDE_ACK message after receiving the WM_DDE_DATA. 
 0=Client is not expected to send ACK. 


1=Client is expected to free the data pointed to by hData. O=Client should not free the data. 
See the Posting and Receiving notes below for exceptions. 


12 fRequested 1=Data is being sent in response to a WM_DDE_REQUEST message: 0=Data is being sent in 


14, 11-0 reserved — 


response to a WM_DDE_, ADVISE message. 
Reserved for Microsoft use. 


Table se : 1. lParam Low-Order Word Flags for WM_ DDE_DATA. 


cfFormat contains the clipboard format being used to store the data. This can be either a 
standard clipboard format, or a special format created with RegisterClipboardFormat(). Value/] 


. isan array of one or more bytes of data being transmitted. This data is in the format specified by 


¢fFormat. Ina warm link, the high-order word in /Param will be NULL. This simply notifies the 


| _ client that new data is available, but does not transmit the data. It is up to the client to post the 


Posting 


4 


Receiving 


WM_DDE_REQUEST message to get the actual data. 


Use PostMessage() to send this message. The Data data block containing the DDEDATA data 
structure must be allocated using GlobalAlloc() with the GMEM_DDESHARE option. If the client 
receiving the data responds with a negative WM_DDE_ACK message, the server should delete 
the hData memory block. hData should also be deleted if the fRelease flag is set to zero, Do not 
set fAckReq and fRelease to zero: With both set to zero, the server will not know when to delete 
the hData memory block. 


A client receiving this message must decide whether or not to respond with a WM_DDE_ACK 


% message. If fAckRegq is 1, post the WM_DDE_ACK, otherwise do not post the message. If fAckReq. 
is 0, delete the altem global atom. IfhData is NULL, a warm link is in progress. The clientcanask _ 
for the data by sending a WM_DDE_REQUEST message, or simply ignore the WM_DDE_MESS- - 


AGE. If hData is not NULL, the hData global memory block should be deleted unless fRelease is | 
2eTO, or fRelease i is 1, and the client decides to respond with a ee WM_DDE_ACK message. 


WM_DDE_ “EXECUTE a . -- hee mWin2.0, wWin3.0 wmWin3.1 


Purpose 
Syntax 
Discussion 


“ho 


Sends one or more command strings to the client application. . 
PostMessage (HWND hWnd, WM_DDE_EXECUTE; WORD wParam, DWORD Param); 


This is a convenient way to send character string commands from the server to the client applica- 
tion. The commands are stored in a global memory block containing a null-terminated character 
string. The command strings are in the format 


Ccommand(parameters)] 


The square brackets are part of the transmitted string. There can be more than one com- . 
mand in the character string. Here are several examples of valid commands 


! 
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CstartuplCfilefunction(data.txt,7) ]£shutdown] 
Cpassname("This is the string data passed.")J 


Parameters 

hWnd HWND: The window handle of the window to receive the message. 

wParam WORD: The window handle of the window sending the message. 

lParam DWORD: The low-order word is reserved. The high-order word contains a handle to a global 
memory block containing the command string. The block must be allocated with the 

. GMEM_DDESHARE option. 

Posting Use PostMessage() to post this message. The server sending this message should wait for the 
WM_DDE_ACK message to come back from the client before deleting the memory block contain- 
ing the command string. 

Receiving Respond to receiving this message by posting a WM_DDE_ACK message. Reuse the hCommands 
handle in sending the WM_DDE_ACK message back. 

WM_DDE_INITIATE mWin20 mWin30 mWin31 

Purpose Starts a DDE conversation. 

Syntax SendMessage (HWND hWnd, WM_DDE_INITIATE , WORD wParam, DWORD /Param) 

Discussion When an application receives this message, it should check to see if the application name and 
data name held by the atoms in {Param match the application’s name and data supported. If so, 
the application should respond with a WM_DDE_ACK message. Otherwise, the message is ig- 
nored. ; 

Parameters . 

hWnd HWND: The window handle of the window to receive the message. 

wParam WORD: The window handle of the window sending the message. | 

lParam DWORD: The low-order word contains a global atom holding the name of the application. This 
parameter is called aApplication. The application name cannot contain slashes or backslashes, 
as these characters are reserved for future network support. If aApplication is NULL, any appli- 
cation can respond. 

The high-order word contains a global atom holding the name of the data element. This pa- 
rameter is called aTopic. If aTopic is NULL, any topic is valid. Upon receiving a WM_DDE_INI- 
TIATE message with a NULL value for aTopic,.the application should send a WM_DDE_ACK 
message for every topic it supports. 

Sending Use SendMessage() to transmit this message, not PostMessage(). The message can be sent to 

_ every application running on the system by setting the first parameter of SendMessage() to —1. 
_ The window handle(s) for applications that respond can be obtained from the returning 
' WM_DDE_ACK message(s). . 

Delete the two global atoms containing the application and topic names immediately after 
calling SendMessage(). You do not have to wait for the WM_DDE_ACK message(s) to come back 
to delete these atoms. 

Receiving Post a WM_DDE_ACK message for each topic supported if the application name matches. If a 


The square brackets are required around each command. 


topic is specified, post a WM_DDE_ACK only if the topic is supported. The receiving application 
should create new aApplication and aTopic atoms. Do not use the atoms sent with 
WM_DDE_INITIATE, as the sending application is expected to delete them. 
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WM_DDE_POKE | wWin2.0 3 mWin30- mWin3l 


Purpose — This message is posted by the client application sending unsolicited data to the server. 

Syntax PostMessage (HWND hWnd, WM_DDE_POKE, WORD wParam, DWORD lParam); 

Discussion WM_DDE_POKE allows the client to send fad server data de meponcent of when the server ini- 
tiates data C3 xchange. 

Parameters BY dy 

hWnd HWND: The window handle of the window to receive the message. 

wParam WORD: The window handle of the window sending the message. 

lParam DWORD: The high-order word contains a global atom containing the name of the data item being 


transmitted. This parameter is called altem. The low-order word contains a handle (called 
hData) to a global memory block containing a DDEPOKE ote structure. This structure contains 
bit fields, and is defined in DDE.II as follows: - “ 


typedef struct ¢ 


unsigned unused:13, 
fRelease:i, /* 1= receiver frees memory */ 
; fReserved:2; : 
int | cfFormat; , /* clipboard data format used */  - 
BYTE Valuel1]; '/*® this may be > 1 byte */ 


} DDEPOKE; 


If the Reserved field is set to 1, the application receiving the WM_DDE_POKE message is 
expected to free the global memory block containing the DDEPOKE data structure. IffReserved 
is 0, the block should not be freed. 

cfFormat contains the clipboard format being used to site the chs This can be either a 
standard clipboard format, or a special format created with RegisterClipboardFormat(). 

Value/) is an array of one or more bytes of data being transmitted. This data is in the format 
specified by ¢fFormat. 


Posting Use PostMessage() to transmit this message, not se CouiMesaaE, Use tiie GMEM _DDESHARE 
“option when calling GlobalAlloc() to allocate memory to hold the DDEPOKE data structure. 
The sending application is responsible for deleting the memory block if the fRelease flag is 
set to zero. In this case, the sending application should wait for the WM_DDE_ACK message to 
come back before deleting the data. : 7 


Receiving An application receiving this message should respond with a WM_DDE_ACK message. The 
‘ WM_DDE_ACK can reuse the altem atom, or it can delete the received atom and create a new 
one. After receiving WM_DDE_ POKE, the application should delete the global memory block 

hDatunless fRelease is zero. 


WM_DDE_REQUEST . wWin2.0 mWind0 Wind! 
| Purpose = -__— Posted by the client application to prompt transmittal of a data item from the server. 

Syntax : PostMessage (HWND IVnd, WM_DDE_REQUEST, WORD wParam, DWORD lParam); 
Discussion . _—_‘ This message is sent as part of a warm link. If the client receives a WM_DDE_DATA message with 


a NULL data item, the server is indicating that a data item has changed and a new value is avail- 
able. AWM_DDE_REQUEST can then be sent by the client to prompt for the latest data value. 


Parameters. 1 a ss | 
hWnd : HWND: The window handle of the window to receive the message. 


' wParam WORD: The window handle of the window sending the message. 
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lParam DWORD: The low-order word (called cfFormat ) contains the clipboard format being used to 
store the data. This can be either a standard clipboard format, or a special format created with 
RegisterClipboardFormat(). The high-order word (called a/tem) contains a global atom contain- 
ing the data item name being requested. 

Posting Use PostMessage() to transmit this message, not SendMessage(). 

Receiving The receiving application normally will respond by posting a WM_DDE_DATA message contain- 
ing the requested data. Otherwise, it should post a WM_DDE_ACK message containing a nega- 
tive response. In either case, the global atom a/tem can either be reused, or deleted and a new 
atom created. 

WM_DDE_TERMINATE . Win2.0 esWin30 mWin3.1 

Purpose Stops a DDE conversation. 

Syntax PostMessage (HWND hWnd, WM_DDE_TERMINATE, WORD wParam, DWORD lParam); 

Discussion This message notifies either a client or server application that the DDE conversation is termi- 
nated. 

Parameters . 

hWnd HWND: The window handle of the window to receive the message. 

wParam WORD: The window handle of the window sending the message. 

lParam DWORD: Not used. Set equal to OL. 

Posting Use PostMessage() to transmit this message, not SendMessage(). After posting this message, the 
application should not respond to any other messages from the application receiving the mes- 
sage, other than WM_DDE_TERMINATE. 

Receiving Respond by posting a WM_DDE_TERMINATE message. Do not respond to this message if the 
receiving application initiated WM_DDE_TERMINATE (to avoid an infinite loop of messages). 

WM_DDE_UNADVISE Win2.0 wWin3.0 mWin3.l 

Purpose Sent by the client application to stop updates of a particular item in a warm or hot link. 

- Syntax PostMessage (HWND hWnd, WM_DDE_UNADVISE, WORD wParam, DWORD lParam); 

Discussion After a WM_DDE_ADVISE message is received by the server, the server is expected to send a 
WM_DDE_DATA message when the data item changes. WM_DDE_UNADVISE stops this process, 
temporarily stopping hot or warm link WM_DDE_DATA messages. - 

Parameters 

| hWnd HWND: The window handle of the window to receive the message. 

wParam WORD: The window handle of the window sending the message. 

lParam DWORD: The low-order word (called ¢fFormat ) contains the clipboard format being used to 
store the data. This can be either a standard clipboard format, or a special format created with 
RegisterClipboardFormat(). The high-order word (called a/tem) contains a global atom contain- 
ing the data item name being retracted. If altem is NULL, all WM_DDE_ADVISE conversations 
associated with the client application are terminated. 

Posting Use PostMessage() to transmit this message, not SendMessage(). 

Receiving 


Post the WM_DDE_ACK message to respond to this message. 
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Appendix A 
Bibliography and Sources 
of Additional Information: 


Books on Windows 


Charles Petzold’s book is an excellent tutorial on programming under Windows. It covers all the basic elements of 
Windows and several more advanced topics, ipeuaing 2 DDE and MDI. 

Programming Windows 

Charles Petzold 

Microsoft Press, 1990 


The Norton and Yao book is slower paced and easier to digest than Petzold’s book, but it covers less material. 
Windows 3.0 Power Programming Techniques - 
Peter Norton and Paul Yao — 
Bantam Books, 1990 


Jeffrey Richter’s book covers a number of advanced topics, including dynamic dialog boxes, custom controls, printer 
setup, and program installation. It is intended for readers who have already mastered the material in the Petzold, or 
Norton and Yao books. ; 
Windows 3: A Developer’s Guide 
Jeffrey M. Richter 
M&T Books, 1991 


Other Programming Reference Books 

This IBM document spells out the rules for programming the user interface for Windows and OS/2 applications. Fol- 

lowing these guidelines is strongly encouraged. 
Systems Application Architecture, 
Common User Access Advanced Interface Design Guide 
International Business Machines, 1989 


The classic Kerninghan and Ritchie book is the standard reference for the C language. 
The C Programming Language, Second Edition 
Brian W. Kerninghan and Dennis M. Ritchie 
Prentice Hall, 1988 


If you need a more readable introduction to the C language, try the Waite and Prata book. 
The Waite Group’s New C Primer Plus 
Mitchell Waite and Stephan Prata 
The Waite Group, 1990 
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For a thorough understanding of the MS-DOS operatine ten asi underlies Windows, tates to the Microsoft Press : 

Encyclopedia. 
The MS-DOS Encyclopedia 
Ray Duncan, General Editor 
Microsoft Press, 1988 


For additional acemand on digital communications, refer to Paul Bate's book. 
Practical Digital and Data Communications 
Paul Bates . 
~’ Prentice-Hall, 1987 


Sound Driver Support and Information 


Users of the popular Sound Blaster and Adlib music cards can obtain an excellent Windows driver that was developed 
at the University of Wisconson. 
Monty Schmidt 
1020 E. Johnson #1 
Madison, WI 53703 
(608) 256-3133 
_ COMPUSERVE 73020, 2770 


For more complete control of all of the Sound Blaster features, Creative Labs, Inc. offers a DLL (dynamic link library). 
The DLL includes support of both the synthesized sound, and voice record/playback functions. . 

Creative Labs, Inc. 

2050 Duane Ave. 

Santa Clara, CA 95954 _ 

, (408) 986- 1461 * 


MIDI drivers are available from Microsoft as part of their Multimedia Development Kit, or separately from Playroom 
Software. 
Microsoft Corporation 
16011 NE 36th Way 
Box 97017 
_ Redmond, WA 98073- 97 17 
(206) 426-9900 . 


Playroom Software 

7308-C East Independence Blvd., Suite alt 
Charlotte, NC 28227 ug ge a aa 
(704) 536- ots Z 


The MIDI (Musical Instrument Digital Interface) specification i is available from the ternational MIDI Association. 
International MIDI Association : ; by Be 
5316 W. 57th St. 
Los Angeles, CA 90056 
(213) 649-6434 
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Useful-Macros from WINDOWS.H 


WINDOWS.H contains a srabee of useful. #define statements that define macros. mney can be used to Iniprave the 
clarity of an application’s code and maintain strong type checking. 

The following three macros extract one of the color values from the compcsite 32-bit color value used with either 
the RGB color model, or a color palette. 


GetBValue(rgb) CCBYTE) CC rgb)>>16) ) 
GetGValue(rgb) CCBYTE) CC CWORD) (rgb)) >> 8)) 
GetRValue(rgb) (C(BYTE) (rgb)) 


It is frequently necessary to extract one-half of either a 16-bit WORD or a 32-bit DWORD value when processing 
Windows messages. 


HIBYTE Cw) CCBYTE) CCCWORD) (Cw) >> 8) & OxFF)) 
HIWORD(L) CCWORD) CC COWORDI CL) >> 16) & OxFFFF)) 
LOBYTE(w) ((BYTE) Cw) 

LOWORDC(L) CCWORD) CLD) 


WINDOWS.H contains several macros for casting values to different types. The MAKELONG macro.combines two 
WORD values to make a DWORD. Note that the low-order WORD is placed first in the macro. 


MAKEINTATOMC 4) CLPSTR) CCOWORD) CCWORD)C7))) 
MAKELONG(a, b) CCLONG) CCCWORD) Cad) | CCDWORD) CCWORD)(b))) << 16)) 
MAKEPOINTCL) (*C(CPOINT FAR *)&(L))) 


The min and max macros return the smaller or larger of two values. 


max(a,b) ((Ca) > Cb)) 2? Cad : (bd) 
min (a,b) (€Ca)d < (bd) 2? Cad : Cbd) 


The palette manager uses the high-order byte of the color value to be coded if the color entry is a palette index or 
a palette RGB value. The RGB macro combines three byte values to make a DWORD color value. . 


PALETTEINDEXC 1) ((CDWORD) (0x01000000 | (woRD)(i))). ° 
PALETTERGB(r,g,b) (Ox02000000 | RGB(r,g,b)) 
RGBC(r,g,b) (CCDWORD) CCCBYTE) Cr) | CC WORD) (g)<<8)) | (CCDWORD) (BYTE) (b) )<<16))) 
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HTERROR 
HTTRANSPARENT 
HTNOWHERE 
HTCLIENT 
HTCAPTION 
HTSYSMENU 
HTGROWBOX 
HTSIZE 
HTMENU 
HTHSCROLL 
HTVSCROLL ~ 
HTREDUCE 
HTZOOM 


HTBOTTOMLEFT - 


HTBOTTOMRIGHT 
HTSIZEFIRST 
_ HTSIZELAST 
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“Appendix C 
Mouse Hit Test Codes 


Ne Need 


GROWBOX .. 


HTLEFT 
HTBOTTOMRIGHT 
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Appendix D 
WINDOWS.H Listing 


Include file for Windows 3.0 applications */ 


If defined, the following flags inhibit definition 
of the indicated items. 


NOGDICAPMASKS 


NOVIRTUALKEYCODES 


NOWINMESSAGES 
NOWINSTYLES 
NOSYSMETRICS 
NOMENUS 
NOICONS 
NOKEYSTATES 
NOSYSCOMMANDS 
NORASTEROPS 
NOSHOWWINDOW 
OEMRESOURCE 
NOATOM 
NOCLIPBOARD 
NOCOLOR 
NOCTLMGR 
NODRAWTEXT 
NOGDI 
NOKERNEL 
NOUSER 

NOMB 

NOMEMMGR 
NOMETAFILE 
NOMINMAX 
NOMSG 
NOOPENFILE 
NOSCROLL 
NOSOUND 
NOTEXTMETRIC 
NOWH 
NOWINOFFSETS 
NOHELP 
NOPROFILER 
NODEFERWINDOWPOS 
NODRIVERS 
NODBCS 
NOSYSPARAMSINFO 
NOSCALABLEFONT 


“USECOMM 


Defining the following 


PRINTING 


“MB_* and MessageBox() 


cc_*, LC_*, PC_*, CP_*, TC_*, RC_ 
VK_* 

WM_*, EM_*, LB_*, CB_* 

wS_*, CS_*, ES_*, LBS_*, SBS_*, CBS_* 
SM_* 

MF_* 

IpI_* 

MK_* 

sc_* 

Binary and Tertiary raster ops 
SW_* 

OEM Resource values 

Atom Manager routines 

Clipboard routines 

Screen colors 


ah 


‘Control and Dialog routines 


DrawText() and DT_* 

ALL GDI defines and routines 

ALL KERNEL defines and routines 

ALL USER defines and routines : 
GMEM_*, LMEM_*, GHND, LHND, associated routines 
typedef METAFILEPICT 

Macros min(a,b) and max(a,b) 

typedef MSG and associated routines 
OpenFile(), OemToAnsi, AnsiToOem, and OF_* 
SB_* and scrolling routines | 

Sound driver routines 

typedef TEXTMETRIC and associated routines 
SetWindowsHook and WH_* 

GWL_*, GCL_*, associated routines 

Help engine interface. 

Profiler interface. 

DeferWindowPos routines 

Installable driver defines 

DBCS support stuff. 

SystemParameterInfo (SPI_*) 

Scalable font prototypes and data structures: 


Include COMM driver routines 


allows API's to be included 
- include printing api's 
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 #ifdef RC_INVOKED 


/* Turn off a bunch of stuff to ensure that RC files eoantle OK. */ 
#define NOATOM 

#define NOGDI 

‘Hdefine NOGOICAPMASKS 
H#define NOMETAFILE 
Hdefine NOMINMAX 
#define NOMSG 

H#define NOOPENFILE 
define NORASTEROPS 

. Adefine NOSCROLL 
#define NOSOUND 

#define NOSYSMETRICS 
#define NOTEXTMETRIC 
#define NOWH . 

Hdefine NODBCS 

Hdefine NOSYSPARAMSINFO 


Hendif /* RC_LINVOKED */ 


[ Bere nr nr en rn a rn nn ne een nnn nn nen n= ef. 
/* General Purpose Defines */ 
[RSSee Sess oS e neste eee sc scs ese scceascsuenccsewecnwesckesseus */ 
#define NULL 0 

Hdefine FALSE 0 

H#define TRUE 1 

Hdefine FAR far 

H#define NEAR ~ near 

#define LONG long 

H#define VOID void 

Hdefine PASCAL pascal 

H#define API _ far pascal 

H#define CALLBACK far pascal 

#ifndef NOMINMAX 

#ifndef max | 

#define max(a,b)  €Cad > (Cb) 2? Cad: Cbd.” 

Hendif Ba SS at ie By 

Hifndef min . a 

H#define min(a,b) oy €CCa) < Cbd) 2 Cad : Cb)) 


Hendif 


Hendif /* NOMINMAX */ 


wd 


#define MAKELONG(a, b) (CLONG) \¢CWORD) a)? 1. CCDWORD) CCWORD) (BI) << 16)) 
H#define LOWORD(L) CCWORD) (U3) 


. H#define HIWORD(L) (CWORD).CCCDWORD) (L) >> 16) & OxFFFF))- 
H#define LOBYTE(w) ( (BYTE) Cw) 
#define HIBYTECw) (CBYTE) CC CWORD) Cw) >> 8). & OxFF)). 


Hdefine MAKELP(sel, off) CCVOID FAR * )MAKELONG (off, aeh7? 
Adefine SELECTOROF(Lp) HIWORD(Lp) : 
Adefine OFFSETOFCLp) LOWORDC Lp) 


typedef int ' BOOL; 
typedef unsigned char BYTE; 
typedef unsigned short WORD;. 
typedef unsigned Long DWORD; 


typedef char near *PSTR; : 
' typedef char near *NPSTR; 

typedef char far, *LPSTR; 

typedef BYTE near *PBYTE; 

typedef BYTE far *LPRYTE; 
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typedef int near *PINT; 
typedef int far *LPINT; 
typedef WORD near *PWORD; - 
typedef WORD far *LPWORD; 
typedef long near *PLONG; 
typedef long far *LPLONG; 
typedef DWORD near *PDWORD; 
typedef DWORD far *LPDWORD; 
typedef void far *LPVOID; 


#ifdef STRICT 
Hdefine DECLARE_HANDLE (name) \ 
typedef struct _#4#name##_ € int dummy; }; \ 
typedef struct _##name##_ near *name 
typedef void near* HANDLE; 
DECLARE_HANDLECHWND) ; 
Helse /*® STRICT */ 
\ 
H#define DECLARE_HANDLE(name) \ 
typedef WORD name 
typedef WORD HANDLE; 


DECLARE_HANDLECHWND); 


Hendif /* !STRICT */ 


/* Special value for CreateWindow, et al. */ 


#def ine. HWND_DESKTOP CCHWND NULL) 
typedef HANDLE *PHANDLE; 
typedef HANDLE NEAR * SPHANDLE; 

’ typedef HANDLE FAR *LPHANDLE; 
typedef HANDLE GLOBALHANDLE; 
typedef HANDLE LOCALHANDLE; 


typedef int (FAR PASCAL *FARPROC)();_ 
typedef int (NEAR PASCAL *NEARPROC)(); 


DECLARE_HANDLECHSTR); 
DECLARE_HANDLECHICON); 
DECLARE_HANDLECHDC); 
DECLARE _HANDLECHMENU); 
DECLARE_HANDLECHPEN) ; 
DECLARE_HANDLECHFONT); 
DECLARE_HANDLECHBRUSH) ; 
DECLARE_HANDLECHBITMAP) ; 
DECLARE_HANDLECHCURSOR); 
DECLARE_HANDLECHREN) ; 
DECLARE_HANDLECHPALETTE); 


typedef DWORD COLORREF; 


typedef struct tagRECT 
{ 
int left; 
int top; 
int right; 
‘int bottom; 
} RECT; 


typedef RECT ' *PRECT; 


typedef RECT NEAR *NPRECT; 
typedef RECT FAR *LPRECT; 
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typedef struct tagPOINT 

{ 

int xX; 

int ys 

} POINT; 
typedef POINT *PPOINT; 
typedef POINT NEAR *NPPOINT; 
typedef POINT FAR *LPPOINT; 


 #ifndef NOKERNEL 


_/*® Loader eyeanes: */ 

DWORD API GetVersion(void); 

WORD API GetNumTasks(void); 

HANDLE API GetCodeHandle(FARPROC); 

void API GetCodeInfoCFARPROC LpProc, LPVOID lpSegInfo); 
HANDLE API GetModuleHandle(LPSTR); 


int API GetModuleUsage (HANDLE); 
int - API GetModuleFileName(HANDLE, LPSTR, int);. 
int API GetInstanceData(HANDLE, NPSTR, int); 


FARPROC API GetProcAddress(HANDLE, LPSTR); 
FARPROC API MakeProcInstance(FARPROC, HANDLE); 
‘void ~ API FreeProcInstance(FARPROC); 
HANDLE API LoadLibrary(LPSTR); 

HANDLE API LoadModule(LPSTR, LPVOID); 
void API FreeModuleCHANDLE); 

void API FreeLibrary (HANDLE); 

DWORD API GetFreeSpace (WORD); 

WORD API WinExec(LPSTR, WORD); 

void API DebugBreak(void); 

void API OutputDebugString(LPSTR); 

void API SwitchStackBack(void); 

void API SwitchStackTo(WORD, WORD, WORD); 
WORD API GetCurrentPDB( void); 

#ifdef WIN31 

BOOL API IsTaskCHANDLE); 

WORD API Get FreeSystemResources (WORD); 
Hendif 


Hifndef NOOPENFILE 


ay hal OpenFile() Structure */ 
typedef.struct tagOFSTRUCT 


{ 

BYTE - cBytes; 

BYTE fFixedDisk; 

WORD nErrCode; 

BYTE reserved[4]; 

BYTE szPathName(128]; 

} OFSTRUCT; 

typedef OFSTRUCT *POFSTRUCT; 
typedef OFSTRUCT NEAR *NPOFSTRUCT; 
typedef OFSTRUCT FAR _ *LPOFSTRUCT; 
/* OpenFile() Flags */ 
#define OF_READ 0x0000 
H#define OF_WRITE . Ox0001 
Hdefine OF_READWRITE 0x0002 
#define OF _SHARE_COMPAT ; 0x0000 
H#define OF _SHARE_EXCLUSIVE 0x0010 
H#define OF _SHARE_DENY_WRITE 0x0020 
#define OF_SHARE_DENY_READ 0x0030 
#define OF_SHARE_DENY_NONE 0x0040 
H#define OF_PARSE \ 0x0100 
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#define OF_DELETE 
Hdefine OF_VERIFY 


. 0x0200 


0x0400 /* Used with OF_REOPEN */ 


#define OF_SEARCH 0x0400 /* Used without OF_REOPEN */ 
H#define OF_CANCEL 0x0800 

#define OF_CREATE 0x1000 

ddefine OF _PROMPT 0x2000 

#define OF_EXIST 0x4000 

H#define OF_REOPEN 0x8000 

int API OpenFileC(LPSTR, LPOFSTRUCT, WORD); 

int FAR PASCAL OpenSystemFile(LPSTR, LPOFSTRUCT, WORD); 

/* GetTempFileName() Flags */ 

H#define TF_FORCEDRIVE (BYTE)0x80 


BYTE API GetTempDrive(BYTE); 
int API GetTempFileName(BYTE, LPSTR, WORD, LPSTR); 
WORD API SetHandleCount (WORD); 


WORD API GetDriveTypeCint); 
/* GetDriveType return values */ 


#define DRIVE_REMOVAB 
H#define DRIVE _FIXED 
4#define DRIVE _REMOTE 


LE 2 
3 
4 


Hendif /* NOOPENFILE */ 


#ifndef NOMEMMGR 


/* Global Memory Flags */ 


H#define GMEM_FIXED 
#define GMEM_MOVEABLE 
#define GMEM_NOCOMPAC 
#define GMEM_NODISCAR 
#define GMEM_ZEROINIT 
#define GMEM_MODIFY 
#define GMEM_DISCARDA 
4#define GMEM_NOT_BANK 
#define GMEM_SHARE 
#define GMEM_DDESHARE 
#define GMEM_NOTIFY 
H#define GMEM_LOWER 


#define GHND 
#define GPTR 


T 
D 


BLE 
ED 


0x0009 
0x0002 
0x0010 
0x0020 
0x0040 
0x0080 
0x0100 
0x1000 
0x2000 
0x2000 
0x4000 
GHEM_NOT_BANKED 


(GMEM_MOVEABLE | GMEM_ZEROINIT) 
C(GMEM_FIXED | GMEM_ZEROINIT) 


#define GlobalDiscard(h) GlobalReAllocCh, OL, GMEM_MOVEABLE) 


HANDLE API GlobalALlocC(WORD, DWORD); 
DWORD API GlobalCompact(DWORD); 


HANDLE API GlobalFre 
DWORD API GlobalHan 
LPSTR API GlobalLoc 


eCHANDLE); 
dleCWORD); 
kCHANDLE); 


HANDLE API GlobalReAllocC(HANDLE, DWORD, WORD); 


DWORD API GlobalSiz 


eCHANDLE); 


BOOL API GlobaLUnlockCHANDLE) ; 
WORD API Global Flags (HANDLE) ; 


LPSTR API GlobalWir 


eCHANDLE); — 


BOOL API GlobalUnWireCHANDLE); | 
HANDLE API GlobalLRUNewest (HANDLE) ; 
HANDLE API Global LRUOLdest (HANDLE); 
VOID API GlobalNotify(CFARPROC); 
WORD “API Global PageLock(HANDLE) ; 
WORD API Global PageUnlLock(HANDLE) ; 


VOID API Global Fix 
BOOL API GlobalUnf 


CHANDLE); 
ix CHANDLE); 


DWORD API GlobalDosAlloc(DWORD); 


WORD API GlobalDos 


FreeC(WORD); 
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/* Flags returned by GlobalFlags Cin addition to GMEM_DISCARDABLE) *] 


Hdefine GMEM_DISCARDED © 0x4000 ; 
#define GMEM_LOCKCOUNT OxOOFF / 
#define LockData(dummy) LockSegment (OxFFFF) 
define UntockData(dummy) UnlockSegment(OxFFFF) . 


HANDLE API LockSegment (WORD); 
HANDLE API UnlockSegment(WORD); 


#ifdef WIN31 


H#define GlobalAllocPtr(flags, cb) \ | 
CCVOID FAR*)MAKELP(GLobalALloc(( flags), (cb)), 0)) 

‘“Adefine GlobalReALlocPtr(lp, cbNew, flags) \ ; 
((BOOL)GlLobalReAlloc( (HANDLE) SELECTOROF(Lp), (cbNew), (flags))) 


Hdefine GlobalFreePtr(lp) \ 
((BOOL)Global Free( (HANDLE) SELECTOROF(Lp))) 
#define GlobalLockPtr(Lp) \ 


MeL ee 
#define GlobalUnlockPtr(Lp) 
GlobalUnlock( (HANDLE) SELECTOROF (Lp) ) 
Hendif /* WIN31 Hea 


/* Local Memory Flags */ 


#define LMEM_FIXED ’ 0x0000 
define LMEM_MOVEABLE 0x0002 
4define LMEM_NOCOMPACT 0x0010 
. define LMEM_NODISCARD 0x0020 
A#define LMEM_ZEROINIT 0x0040 
#define LMEM_MODIFY 0x0080 
4define LMEM_DISCARDABLE OxOFOO 


Hdefine LHND - (LMEM_MOVEABLE | LMEM_ZEROINIT) 
_ define LPTR (LMEM_FIXED | LMEM_ZEROINIT) 


.Adefine NONZEROLHND (LMEM_MOVEABLE) 
H#define NONZEROLPTR CLMEM_FIXED) 


A#define LNOTIFY_OUTOFMEM 0 
define LNOTIFY_MOVE 1 
Hdefine LNOTIFY_DISCARD 2 


define LocalDiscard(h) LocalReALlocth, 0, LMEM_MOVEABLE) 


HANDLE API LocalAlloc(WORD, WORD); 
WORD API LocalCompact (WORD); 
HANDLE API LocalFree(HANDLE); 
HANDLE API LocalHandleCWORD) ; : 
BOOL API LocalInit( WORD, WORD, WORD); 
' char NEAR * API LocalLockCHANDLE) ; 
_ FARPROC API LocalNotify(FARPROC) ; 
HANDLE API LocalReALLoc(HANDLE, WORD, WORD); 
WORD API LocalSize(HANDLE) ; 
BOOL API LocalUnlockCHANDLE); 
WORD API Local Flags (HANDLE); 
WORD API Pec SMEane HANDLE, WORD); 


|* Flags eeturned by LocalFlags (in addition to LMEM_ DISCARDABLE? */ 
#define LMEM_DISCARDED 0x4000 
#define LMEM_LOCKCOUNT OxOOFF 


Hendif /* NOMEMMGR */ 


LONG ‘API SetSwapAreaSize(WORD); 

VOID API ValidateFreeSpaces(void); 

VOID API LimitEmsPages(DWORD); 
BOOL API SetErrorMode(WORD); 
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VOID 


H#define 


HANDLE 
HANDLE 
BOOL 
LPSTR 
FARPROC 
HANDLE 
DWORD 
int 


#define 


H#ifndef 


Hdefine 


API 


ValidateCodeSegments(void); 


UnlockResource(h) . GlobalUnlock(h) 


API 
API 
API 
API 
API 
API 
API 
API 


FindResource(HANDLE, LPSTR, LPSTR); 
LoadResource(HANDLE, HANDLE); 

FreeResourceCHANDLE); 

LockResource (HANDLE); ; 
SetResourceHandler (HANDLE, LPSTR, FARPROC); 
AllLocResource(HANDLE, HANDLE, DWORD); -- 
SizeofResource(HANDLE, HANDLE); 
AccessResource(HANDLE, HANDLE); 


MAKEINTRESOURCEC i) (CLPSTR)CCDWORD)CCWORD) (C4) )) 


NORESOURCE 


DIFFERENCE 11 


/* Predefined Resource Types */ 


H#define 
H#define 
#define 
#define 
#define 
#define 
#define 
#define 
Hdefine 
#define 


RT_CURSOR MAKEINTRESOURCE(1) 
RT_BITMAP MAKEINTRESOURCE(C2) 
RT_ICON MAKEINTRESOURCE(3) 
RT_MENU MAKEINTRESOURCEC4) 
RT_DIALOG MAKEINTRESOURCE(5) 
RT_STRING MAKEINTRESOURCE(C6) 
RT_FONTDIR MAKEINTRESOURCE(7) 
RT_FONT MAKEINTRESOURCE(8) 
RT_ACCELERATOR MAKEINTRESOURCE(9) 
RT_RCDATA MAKEINTRESOURCE(10) 


/* NOTE: if any new resource types are introduced above this point, then the 
** value of DIFFERENCE must be changed. 

** CRT_GROUP_CURSOR ~ RT_CURSOR) must always be equal to DIFFERENCE 

** CRT_GROUP_ICON - RT_ICON) must always be equal to DIFFERENCE 


*/ 


Adefine RT_GROUP_CURSOR CRT_CURSOR + DIFFERENCE) 
/* The value 13 is intentionally unused */ 
4#define RT_GROUP_ICON CRT_ICON + DIFFERENCE) 


Hendif /* NORESOURCE */ 


void API Yield(void); 
HANDLE API GetCurrentTask(void);° 


WORD API AllocSelector(WORD); 

WORD API FreeSelector (WORD); 

WORD API ALlocDStoCSALias(WORD); 

WORD API ChangeSelector(WORD sourceSel, WORD destSel); 


Hifndef NOATOM 


typedef WORD ATOM; 

#define MAKEINTATOMCi) CLPSTR) CCDWORD) (CCWORD)Ci))) 
BOOL API InitAtomTableCint); 

ATOM API AddAtom(LPSTR); 

ATOM API DeleteAtom(ATOM); 

ATOM API FindAtom(LPSTR); 

WORD API GetAtomName(ATOM, LPSTR, int); 

ATOM API SlobalAddAtom(LPSTR); : 

ATOM - API GlobatDeleteAtom(ATOM); 

ATOM API GlobalFindAtom(LPSTR); 

WORD API GlobalGetAtomNameCATOM, LPSTR, int); 
HANDLE: API GetAtomHandle(ATOM); 


#endif /* NOATOM */ . 


/* User Profile Routines */ 
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WORD API GetProfileIntC(LPSTR, LPSTR, int); 

int API GetProfileString(LPSTR, LPSTR, LPSTR, LPSTR, int); 

BOOL API WriteProfileString(LPSTR, LPSTR, LPSTR);. 

WORD API GetPrivateProfileInt(LPSTR, LPSTR, int, LPSTR); 

int API GetPrivateProfileString(LPSTR, LPSTR, LPSTR, LPSTR, int, LPSTR); 
* BOOL API WritePrivateProfileString(LPSTR, LPSTR, LPSTR, LPSTR); 


WORD API GetWindowsDirectory(LPSTR,WORD) ; 
WORD API GetSystemDirectory(LPSTR,WORD); 


/* Catch () and Throw ) */ 


typedef int CATCHBUFC9I; 
typedef int FAR ®LPCATCHBUF ; 
int API Catch(LPCATCHBUF) ; re 


void API Throw(LPCATCHBUF, int); 
void API SwapRecording(WORD); 
#ifdef WIN31 


void API LogError (WORD err, VOID FAR*® LpInfo); 
void API LogParamError(WORD err, FARPROC Lpfn, VOID FAR* param); 


“t LogError and LogParamError constants */ 
/* Error modifier bits */ 


define ERR_WARNING. 0x8000 
#define ERR_PARAM 0x4000 


/* Parameter error values */ 


&define ERR_BAD_VALUE 0x5001 
Adefine ERR_BAD_FLAGS 0x5002 
tdefine ERR_BAD_INDEX 0x5003 
&define ERR_BAD_DVALUE 0x7004 
Ndefine ERR_BAD_DFLAGS 0x7005 
Adefine ERR_BAD_DINDEX 0x7006 
define ERR_BAD_PTR ; : 0x7007 | 
#define ERR_BAD_FUNC_PTR 0x7008 
#define ERR_BAD_SELECTOR - 0xS009 
define ERR_BAD_STRING_PTR 0x700a 
define ERR_BAD_HANDLE Ox700b. 


/* KERNEL parameter errors */ 


Adefine ERR_BAD_HINSTANCE 0x5020 
#define ERR_BAD_HMODULE 0x5021 
Ndefine ERR_BAD_GLOBAL_HANDLE 0x5022 
define ERR_BAD_LOCAL_HANDLE 0x5023 
#define ERR_BAD_ATOM 0x5024 


/* USER parameter errors */ 


#define ERR_BAD_HWND 0x5040 
- Adefine ERR_BAD_HMENU ; 0x5041 
define ERR_BAD_HCURSOR 0x5042 
f#define ERR_BAD_HICON 0x5043 


/* GDI parameter errors */ 


adefine ERR_BAD_COORDS 0x7060 

#define ERR_BAD_GDI_OBJECT 0x5061 Tying 

#define ERR_BAD_HDC 0x5062 ac 
#define ERR_BAD_HPEN 0x5063 

#detine ERR_BAD_HFONT Ox5064 . 

#define ERR_BAD_HBRUSH ~- 0x5065_ 

#define ERR_BAD_HBITMAP E 0x5066 


define ERR_BAD_HRGN 0x5067 
#define ERR_BAD_HPALETTE 0x5068 
H#define ERR_SIZE_MASK 0x3000 
4define ERR_SIZE_SHIFT 12 

#define ERR_BYTE 0x0000 
#define ERR_WORD 0x1000 
H#define ERR_DWORD 0x3000 


'/* Debug fill constants */ 


define DBGFILL_ALLOC . Oxfd 
A#define OBGFILL_FREE Oxfb 
Adefine DBGFILL_BUFFER Oxf9 


Hdefine DBGFILL_STACK - Oxf? 
Hendif /* WIN31 */ 


void. API FatalExit(int); 
void API FatalAppExitC(WORD, LPSTR); 


/* Character Translation Routines */ 

int API AnsiToOem(LPSTR, LPSTR); 

BOOL API OemToAnsi(LPSTR, LPSTR); 

void API AnsiToOemBuff(LPSTR, LPSTR, int); 
void API OemToAnsiBuffC(LPSTR, LPSTR, int); 
LPSTR API AnsiUpper(LPSTR); 

WORD API AnsiUpperBuff(LPSTR, WORD); 
LPSTR API AnsiLower(LPSTR); 

WORD API AnsiLowerBuff(LPSTR, WORD); 
LPSTR API AnsiNext(LPSTR); 

LPSTR API AnsiPrev(LPSTR, LPSTR); 


Hifdef WIn31 

#ifndef NOOBCS 

BOOL API IsDBCSLeadByte( BYTE ); 
Hendif /* NODBCS */ 

Hendif /* WIN31 */ 


/* Keyboard Information Routines */ 
#ifndef NOKEYBOARDINFO : 
DWOR API OemKeyScanCWORD); 

WORD.° API VkKeyScanCWORD); 
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int API GetKeyboardType(Cint); 

int API GetKBCodePage(void); 

int API GetKeyNameText (LONG, LPSTR, int); 

int API ToAsciiCWORD BVArEKS ys: WORD uScanCode, LPSTR LpKeyState, LPVOID ipChar, ‘WORD wFlags); 
Hendif 


Hifndef NOLANGUAGE 

/* Language dependent Routines */ 

BOOL FAR PASCAL IsCharAlpha(char); 

BOOL FAR PASCAL IsCharAlphaNumeric(char); 
BOOL FAR PASCAL IsCharUpper(char); 

BOOL FAR PASCAL IsCharLower(char); 

Hendif 


LONG API GetWinFlags(void); 


Hdefine WF_PMODE 0x0001 
#define WF_CPU286 0x0002 
Adefine WF_CPU386 0x0004 
Hdefine WF_CPU486 0x0008 
Adefine WF_STANDARD 0x0010 
- define WF_WIN286 0x0010 
. Adefine WF_ENHANCED 0x0020 
adefine WF_WIN386 - 0x0020 
#define WF_CPU086 0x0040 
d#define WF_CPU186 0x0080 
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define WF_LARGEFRAME. | 
#define WF_SMALLFRAME 
H#define WF_80x87 
H#define WF_PAGING 
#define WF_WLO 


/* WEP fSystemExit flag values */ 


0x0100 
0x0200 
0x0400 
0x0800 
0x8000 


#define WEP_SYSTEM_EXIT 1 


Adefine WEP_FREE_DLL 0 


LPSTR API GetDOSEnvironment (void); 


#ifdef OEMRESOURCE 


/* OEM Resource Ordinal Numbers */ 


#define OBM_CLOSE 
define OBM_UPARROW 
#define OBM_DNARROW 
H#define OBM_RGARROW 
H#define OBM_LFARROW 
H#define OBM_REDUCE 
#define O08M_ZOOM 
Hdefine OBM_RESTORE 
H#define OBM_REDUCED 
#define OBM_ZOOMD 
#define OBM_RESTORED 
#define OBM_UPARROWD 
#define OBM_DNARROWD 
#define OBM_RGARROWD 
H#define OBM_LFARROWD 
H#define OBM_MNARROW 
#define OBM_COMBO 
Hifdef WIN31 

H#define OBM_UPARROWI 
. #define OBM_DNARROWI 
#define OBM_RGARROWI 
#define OBM_LFARROWI 
Hendif /* WIN31 */ 


#define OBM_OLD_CLOSE 
H#define OBM_SIZE 
#define OBM_OLD_UPARROW 
Hdetine.OBM_OLD_DNARROW 
Hdefine OBM_OLD_RGARROW 
#define OBM_OLD_LFARROW 
#define OBM_BTSIZE 
#define OBM_CHECK 
#define OBM_CHECKBOXES 
#define OBM_BTNCORNERS 
#define O3M_OLD_REDUCE 
Hdefine OBM_OLD_2Z00M 
H#define OBM_OLD_RESTORE 


H#define OCR_NORMAL 

. #define OCR_IBEAM 
Hdefine OCR_WAIT 
H#define OCR_CROSS 
#define OCR_UP 
H#define OCR_SIZE 
#define OCR_ICON 
H#define OCR_SIZENWSE 
#define OCR_SIZENESW 
#define OCR_SIZEWE 
4define OCR_SIZENS 
H#define OCR_SIZEALL 
Adefine OCR_ICOCUR 


H#define OIC_SAMPLE 
H#define OIC_HAND 


32754 
32753 
32752 
32751 
32750 
32749 
32748 
32747 
32746 
32745 
32744 
32743 
32742 
32741 
32740 
32739 
32738 


32737 
32736 
32735 


‘32734 


32767 
32766 
32765 


32764 . 


32763 
32762 
32761 
32760 
32759 
32758 
32757 
32756 
32755 


32512 
32513 
32514 
32515 
32516 
32640 
32641 
32642 
32643 
32644 
32645 
32646 
32647 


' 32512 


32513 
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#define OIC_QUES 
H#define OIC_BANG 
#define OIC_NOTE 


Hendif /* OEMRESOURCE */ 


#endif /* NOKERNEL */ 


#ifndef NOGDI 


H#ifndef NORASTEROPS 


/* Binary raster ops */ 


H#define R2_BLACK 


#define R2_NOTMERGEPEN 
#define R2_MASKNOTPEN 
#define R2_NOTCOPYPEN 
H#define R2_MASKPENNOT 


4#define R2_NOT 
#define R2_XORPEN 


#define R2_NOTMASKPEN 


H#define R2_MASKPEN 


#define R2_NOTXORPEN 


H#define R2_NOP 


#define R2_MERGENOTPEN 


Hdefine R2_COPYPEN 


H#define R2_MERGEPENNOT 
#define R2_MERGEPEN 


#define R2_WHITE 


/* Ternary raster operations */ 


H#define SRCCOPY 
#define SRCPAINT 
#define SRCAND 
H#define SRCINVERT 
#define SRCERASE 
#define NOTSRCCOPY 


H#define NOTSRCERASE 


#define MERGECOPY 
#define MERGEPAINT 
#define PATCOPY 
#define PATPAINT 
#define PATINVERT 
#define DSTINVERT 
#define BLACKNESS 
#define WHITENESS 


#endif /* NORASTEROPS */ 


/* StretchBlt() Modes */ 
H#define BLACKONWHITE 
#define WHITEONBLACK 
H#define COLORONCOLOR 


/*® PolyFill() Modes */ 


#define ALTERNATE 
#define WINDING 


WN = 


/* Text Alignment Options */ 


#define TA_NOUPDATECP 
#define TA_UPDATECP 


#define TA_LEFT 
-Hdefine TA_RIGHT 
#define TA_CENTER 


Ox0000 _ 
0x0001 


0x0000 
0x0002 
0x0006-- 


32514 
32515 
32516 
BS atemodeukusecn’ */ 
*/ 
ea et or ee Ce */ 
1 #7* 0 x] 
2 /* DPon */ 
3 /* DPna *x/ 
4 /* PN */ 
5 /* PDna */ 
6 /* Dn */ 
7 /* DPx */ 
8 /* DPan */ 
9 /* DPa */ 
10 /* DPxn */ 
11 /*D */ 
12 /* DPno */ 
13. /* P */ 
14 /* PDno */ 
15 /* DPo */ 
16 /* 1 */ 
(CDWORD)Ox00cCc0020 /* 
CDWORD)OxOOEE0O086 /* 
CDWORD)Ox008800C6 /* 
CDWORD)0x00660046 /* 
CDWORD)0x00440328 /* 
CDWORD)0x00330008 /* 
CDWORD)Ox001100A6 /* 
CDWORD)OxOOCOOOCA /* 
CDWORD)OxOOBB0226 /* 
CDWORD)Ox00F00021 /* 
CDWORD)OxOOFBOADS /* 
CDWORD)Ox005A0049 /* 
CDWORD)0x00550009 /* 
CDWORD)Ox00000042 /* 
CDWORD)OxOOFFO062 /* 


dest 
dest 
dest 
dest 
dest 
dest 
dest 
dest 
dest 
dest 
dest 
dest 
dest 
dest 
dest 
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LT | | | | 


source 

source OR dest 
source AND dest 
source XOR dest 


source AND (NOT dest ) 


(NOT source) 


CNOT src) AND CNOT dest) 
Csource AND pattern) 
(NOT source) OR dest 


pattern 
DPSnoo 


pattern XOR dest 


(NOT dest) 
BLACK 
WHITE 
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define TA_TOP - Qx0000 
Hdefine TA_BOTTOM 0x0008 
ddefine TA_BASELINE —0x0018 
Hdefine ETO_GRAYED ~ 

Hdefine ETO_OPAQUE 2 

#define ETO_CLIPPED 4 

Hdefine ASPECT_FILTERING  0x0001 


H#ifndef NOMETAFILE 


/* Metafile Functions */ 


Hdefine META_SETBKCOLOR 0x0201 
#define META_SETBKMODE 0x0102 
#define META_SETMAPMODE 0x0103 
Adefine META_SETROP2 0x0104 
ddef ine META_SETRELABS 0x0105 
#def ine’ META_SETPOLYFILLMODE 0x0106 
H#define META_SETSTRETCHBLTMODE 0x0107 
H#define META_SETTEXTCHAREXTRA é 0x0108 
Hdefine META_SETTEXTCOLOR 0x0209 
Adefine META_SETTEXTJUSTIFICATION Ox020A 
#define META_SETWINDOWORG , Ox020B 
Hdefine META_SETWINDOWEXT 0x020C 
#define META_SETVIEWPORTORG 0x020D 
#define META_SETVIEWPORTEXT 0x020E 
Hdefine META_OFFSETWINDOWORG Ox020F 
_ Adefine META_SCALEWINDOWEXT 0x0400 
' #define META,_OFFSETVIEWPORTORG 0x0211 
define META_SCALEVIEWPORTEXT 0x0412 
#define META_LINETO 0x0213 
#define META_MOVETO 0x0214 
#define META_EXCLUDECLIPRECT 0x0415 
#défine META_INTERSECTCLIPRECT 0x0416 
#define META_ARC 0x0817 
#define META_ELLIPSE 0x0418 
Adefine META_FLOODFILL 0x0419 
define META_PIE Ox081A 
define META_RECTANGLE 0x041B 
Hdefine META_ROUNDRECT 0x061C 
#define META_PATBLT 0x061D 
#define META_SAVEDC OxQ01E 
#define META_SETPIXEL . 0x041F 
#define META_OFFSETCLIPRGN : - 0x0220 
#define META_TEXTOUT : 0x0521 
#define META_BITBLT | ~ 0x0922 
H#define META_STRETCHBLT 0x0B23 
Hdefine META_POLYGON 0x0324 
Hdefine META_POLYLINE ; 0x0325 
define META_ESCAPE 0x0626 
4define META_RESTOREDC 0x0127 
H#define META_FILLREGION 0x0228 
#define META_FRAMEREGION 0x0429 
#define META_INVERTREGION 0x012A 
H#define META_PAINTREGION 0x012B 
Hdefine META_SELECTCLIPREGION 0x012C 
Adefine META_SELECTOBJECT : 0x012D 
define META_SETTEXTALIGN Ox012E 
H#define META_DRAWTEXT ; 0x062F 
Hdefine META_CHORD 0x0830 
A#define META_SETMAPPERFLAGS 0x0231 
fdefine META_EXTTEXTOUT Ox0a32 
#define META_SETDIBTODEV ~ 0x0d33 
#define META_SELECTPALETTE 0x0234 — 
-Adefine-META_REALIZEPALETTE : 0x0035 
_ define META_ANIMATEPALETTE 0x0436 


define META_SETPALENTRIES ; 0x0037 
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#define META_POLYPOLYGON 
Adefine META_RESIZEPALETTE 


#define META_DIBBITBLT 

#detine META_DIBSTRETCHBLT 

4define META_DIBCREATEPATTERNBRUSH 
#define META_STRETCHDIB 


#define META_DELETEQBJECT 


H#define META_CREATEPALETTE 
ddefine META_CREATEBRUSH 

#define META_CREATEPATTERNBRUSH 
#define META_CREATEPENINDIRECT 
Hdefine META_CREATEFONTINDIRECT 
Hdefine META_CREATEBRUSHINDIRECT 
Adefine META_CREATEBITMAPINDIRECT 
#define META_CREATEBITMAP 

4define META_CREATEREGION 


Hendif /* NOMETAFILE */ 


/* GDI Escapes */ 


define NEWFRAME 1 
#define ABORTDOC 2 
#define NEXTBAND 3 
#define SETCOLORTABLE 4 
Hdefine GETCOLORTABLE 5 
#define FLUSHOUTPUT 6 
#define DRAFTMODE 7 
Hdefine QUERYESCSUPPORT 8 
H#define SETABORTPROC 9 
H#define STARTDOC 10 
#define ENDDOC 11 
#define GETPHYSPAGESIZE 12 
H#define GETPRINTINGOFFSET 13 
define GETSCALINGFACTOR14 

#define MFCOMMENT 15 
#define GETPENWIDTH 16 
#define SETCOPYCOUNT 17 
H#define SELECTPAPERSOURCE 18 
#define DEVICEDATA 19 
define PASSTHROUGH 19 
#define GETTECHNOLGY 20 
Hdefine GETTECHNOLOGY , 20 
Hdefine SETENDCAP 21 
define SETLINEJOIN 22 
Hdefine SETMITERLIMIT 23 
Hdefine BANDINFO 24 
Hdefine ORAWPATTERNRECT 25 
define GETVECTORPENSIZE 26 
#define GETVECTORBRUSHSIZE 27 
H#define ENABLEDUPLEX 28 
Hdefine GETSETPAPERBINS 29 
Hdefine GETSETPRINTORIENT 30 
Hdefine ENUMPAPERBINS 4 
Hdefine SETDIBSCALING 32 
define EPSPRINTING ‘ 33 
ddefine ENUMPAPERMETRICS 34 
H#define GETSETPAPERMETRICS 35 
#define POSTSCRIPT_DATA 37 
H#define POSTSCRIPT_IGNORE 38 
Hdefine MOUSETRAILS ' 39 
H#define GETEXTENDEDTEXTMETRICS 256 
#define GETEXTENTTABLE 257 
#define GETPAIRKERNTABLE 258 
#define GETTRACKKERNTABLE 259 


| Adefine EXTTEXTOUT , 512 


0x0538 
0x0139 


- 0x0940 


0x0b41 
0x0142 
Ox0f43 


0x01f0 


Ox00f7 
Ox00F8 
0x01F9 
OxO2FA 
Ox02FB 
Ox02FC 
Ox02FD 
Ox06FE 
OxO6FF 
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#define 
#define 
#define 
#define 
Hdefine 


#define 


#define 
‘Hdefine 
H#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
Hdefine 
Hdefine 
Hdefine 


/* Spool 
#define 
H#define 
#define 
H#define 
#define 
#define 


#define 


/* Object Definitions for EnumObjects() */ 


ENABLERELATIVEWIDTHS 
ENABLEPAIRKERNING 
SETKERNTRACK 
SETALLJUSTVALUES 
SETCHARSET 


GETSETSCREENPARAMS 


STRETCHBLT 
BEGIN_PATH 
CLIP_TO_PATH 
END_PATH 
EXT_DEVICE_CAPS 
RESTORE_CTM 
SAVE_CTM 
SET_ARC_DIRECTION 
SET_BACKGROUND_COLOR 
SET_POLY_MODE 
SET_SCREEN_ANGLE 
SET_SPREAD 
TRANSFORM_CTM 
SET_CLIP_BOX 
SET_BOUNDS 


er Error Codes */ 
SP_NOTREPORTED 
SP_ERROR 
SP_APPABORT 
SP_USERABORT 
SP_OUTOFDISK 
SP_OUTOFMEMORY 


PR_JOBSTATUS 


H#define OBJ_PEN 


768 
769 
770 
771 
772 


. 800 


2048 
4096 
4097 
4098 
4099 
4100 
4101 
4102 
4103 
4104 
4105 
4106 
4107 
4108 
4109 


0x4000 
(-1) 
(-2) 
(-3) 
(-4) 
(-5) 


0x0000 


1 


#define OBJ_BRUSH 2 
/* Bitmap Header Definition */ 
typedef struct tagBITMAP 
{ 
int bmType; 
tnt bmWidth; 
int bmHeight; 
int bmWidthBytes; 
BYTE bmPlanes; 
BYTE bmBitsPixel; 
LPSTR bmBits; 
>} BITMAP; 
typedef BITMAP *PBITMAP; 
typedef BITMAP NEAR *NPBITMAP; 
typedef BITMAP FAR *LPBITMAP; 
typedef struct tagRGBTRIPLE { 
BYTE | rgbtBlue; 
BYTE | rgbtGreen; 
BYTE | rgbtRed; 
} RGBTRIPLE; 
| 
typedef struct tagRGBQUAD { 
BYTE rgbBlue; 
BYTE rgbGreen; 
BYTE rgbRed; 
BYTE rgbReserved; 
} RGBQUAD; 


/* structures for defining DIBs */ 
typedef struct tagBITMAPCOREHEADER € 
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DWORD bcSize; /* used to get to color table */ 
WORD bcWidth; 

WORD bcHeight; 

WORD bcPlanes; 

WORD bcBitCount; 


} BITMAPCOREHEADER; 
typedef BITMAPCOREHEADER FAR *LPBITMAPCOREHEADER; 
typedef BITMAPCOREHEADER *PBITMAPCOREHEADER; 


typedef struct tagBITMAPINFOHEADER{ 


DWORD biSize; 

DWORD biWidth; 

DWORD biHeight; 

WORD biPlanes; 

WORD biBitCount; 

DWORD biCompression; 

DWORD biSizelmage; 

DWORD bixPelsPerMeter; 

DWORD biYPelsPerMeter; 

DWORD: bictruUsed; 

DWORD biclsimportant; 
} BITMAPINFOHEADER; 
typedef BITMAPINFOHEADER FAR *LPBITMAPINFOHEADER; 
typedef BITMAPINFOHEADER *PBITMAPINFOHEADER; 


/* constants for the biCompression field */ 
#define BI_RGB OL 
#define BILRLE8 1L 
H#define BI_LRLE4 2L 


typedef struct tagBITMAPINFO { 


BITMAPINFOHEADER bmiHeader; 
RGBQUAD bmiColorsfi]; 
} BITMAPINFO; 
typedef BITMAPINFO FAR *LPBITMAPINFO; 
typedef BITMAPINFO *PBITMAPINFO; 
typedef struct tagBITMAPCOREINFO ¢ 
BITMAPCOREHEADER bmciHeader; 
RGBTRIPLE bmciColorsl1]; 
} BITMAPCOREINFO; : 
typedef BITMAPCOREINFO FAR *LPBITMAPCOREINFO; 
typedef BITMAPCOREINFO *PBITMAPCOREINFO; 
typedef struct tagBITMAPFILEHEADER € 
WORD bfType; 
DWORD bfSize; ™: 
WORD bfReservedi1; 
WORD bfReserved2; 
DWORD bfOffBits; 
} BITMAPFILEHEADER; 
typedef BITMAPFILEHEADER FAR *LPBITMAPFILEHEADER; 
typedef BITMAPFILEHEADER ; *PBITMAPFILEHEADER; 
#define MAKEPOINT(CL) C*CCPOINT FAR *)&CL))) 


#ifndef NOMETAFILE 


/* Clipboard Metafile Picture Structure */ 
typedef struct tagHANDLETABLE 


{ 
HANDLE objectHandlel1J]; 
3} HANDLETABLE; 
typedef HANDLETABLE *PHANDLETABLE; 
typedef HANDLETABLE FAR *LPHANDLETABLE; 
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typedef struct tagMETARECORD 
{ 


DWORD rdSize; 
WORD rdFunction; 
WORD : rdParmC[13; 
} METARECORD; 
typedef METARECORD ®PHETARECORD; 
typedef METARECORD FAR *LPMETARECORD; 


typedef struct tagMETAFILEPICT 
{ 


int am; 
int xExt; 
int yExt; 
HANDLE hMF; 
)} METAFILEPICT; 
typedef METAFILEPICT FAR *LPMETAFILEPICT; 


typedef struct tagMETAHEADER 
€ 


WORD mtType; 

WORD mtHeaderSize; 
WORD atVersion; 
DWORD mtSize; 
WORD mtNoObjects; 
DWORD mtMaxRecord; 
WORD mtNoParameters; 


} METAHEADER; 

Hendif /* NOMETAFILE */ 
Hifndef NOTEXTMETRIC 

Bo struct tagTEXTMETRIC 


int tmHeight; 

int tmAscent; 

int tmDescent; 

int tmInternalLeading; 

int tmExternalLeading; 

int tmAveCharWidth; 

int tmMaxCharWidth; 

int tmWeight; 

BYTE tmitalic; 

BYTE tmUnderLlined; a 

BYTE tmStruckOut; 

BYTE tmFirstChar; 

BYTE tmLastChar; 

BYTE tmDefaultChar; 

BYTE tmBreakChar; 

BYTE tmPitchAndFamily; 

BYTE tmCharSet; 

int tmOverhang; 

int tmDigitizedAspectX; 

int tmDigitizedAspectY; 
} TEXTMETRIC; 


typedef TEXTMETRIC *PTEXTMETRIC; 
‘typedef TEXTMETRIC NEAR *NPTEXTMETRIC; 
typedef TEXTMETRIC FAR *LPTEXTMETRIC; 


typedef struct tagNEWTEXTMETRIC 
{ 


int tmHeight; 

int tmAscent; 

int tmDescent; 

int tmInternalleading; 
int tmExternalLeading; 
int tmAveCharWidth; 
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int 
int 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
int 
int 
int 
DWORD 
WORD 
WORD 
WORD 


teMaxCharWidth; 
taWeight; 
tmIitalic; . 
tmaUnder lined; 
taStruckOut; 
taFirstChar; 
tmLastChar; 
tmDefaultChar; 
taBreakChar; 
tmPitchAndFamily; 
taCharSet; 
tmOverhang; 
tmDigitizedAspectXx; 
tmDigitizedAspectY; 
ntaFlags; 
ntmSizeEM; 


ntaCellHeight; 
ntmAvgWidth; 


> NEWTEXTMETRIC; 


/* various flags (fsSelection) */ 

/* size of EM */ 

/* height of font in notional units */ 
/* average with in notional units */ 


typedef NEWTEXTMETRIC *PNEWTEXTMETRIC; 
typedef NEWTEXTMETRIC NEAR *NPNEWTEXTMETRIC; 
typedef NEWTEXTMETRIC FAR *LPNEWTEXTMETRIC; 
Hdefine NTM_REGULAR 0x00000040 /* possible ntmFlags bits */ 


#define NTM_BOLD 
#define NTM_ITALIC 


Hendif /* NOTEXTMETRIC */ 


/* GDI Logical Objects: */ 


/* Pel Array */ - 
typedef struct tagPELARRAY 
{ ; 


int 
int 
int 
int 
BYTE 


} PELARRAY; 


paXCount; 
paYCount; 
paXExt; 
paYExt; 
paRGBs; 


0x00000020 
0x00000001 


*PPELARRAY; 


typedef PELARRAY 
typedef PELARRAY NEAR *NPPELARRAY; 
typedef PELARRAY FAR - SLPPELARRAY; 


/* Logical Brush Cor Pattern) */ 


typedef struct tagLOGBRUSH 
€ 


WORD ibStyle; 
DWORD lbColor; 
int lbHatch; 
} LOGBRUSH; 
typedef LOGBRUSH *PLOGBRUSH; 
typedef LOGBRUSH NEAR *NPLOGBRUSH; 
typedef LOGBRUSH FAR SLPLOGBRUSH; 
typedef LOGBRUSH PATTERN; 
typedef PATTERN *PPATTERN; 
typedef PATTERN NEAR *NPPATTERN; 
- typedef PATTERN FAR *LPPATTERN; 
/* Logical Pen */ 
typedef struct tagLOGPEN 
{ 
WORD LopnStyle; 
POINT . lopnWidth; 
DWORD topnColor; 
> LOGPEN; ; 
typedef LOGPEN -_. *PLOGPEN; 
typedef LOGPEN NEAR | ®NPLOGPEN; 


WINDOWS API BIBLE 


typedef LOGPEN FAR 


*LPLOGPE 


typedef struct tagPALETTEENTRY { 


BYTE peRed; 

BYTE peGreen; 
BYTE peBlue; 
BYTE peFlags; 


} PALETTEENTRY; 


typedef PALETTEENTRY FAR 


/* Logical Palette */ 


typedef struct tagLOGPALETTE ¢. 


WORD palVersi 


on; 


WORD palNumEntries; 
PALETTEENTRY palPalEntryliJ; 


} LOGPALETTE; 
typedef LOGPALETTE 


*PLOGPAL 


N; 


*LPPALETTEENTRY; 


ETTE; 


typedef LOGPALETTE NEAR *NPLOGPALETTE; 


typedef LOGPALETTE FAR 


/* Logical Font */ 
#define LF_FACESIZE 


typedef struct tagLOGFON 
{ ; 

int (fHeight; 
int ULfWidth; 
int ULfEscapement; 
int lfOrientation; 
int lfWeight; 
BYTE tfitalic; 
BYTE LfUnderline; 
BYTE lfStrikeOut; 
BYTE LfCharSet; 
BYTE LfOutPrecision; 


BYTE LfClipPrecision; 


BYTE LfQuality; 


*LPLOGPA 
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BYTE LfPitchAndFamily; 
BYTE (fFaceNameCLF_FACESIZE]; 


} LOGFONT; 
typedef LOGFONT 
typedef LOGFONT NEAR 
typedef LOGFONT FAR 


*NPLOGFO 
*LPLOGFO 


#define OUT_DEFAULT_PRECIS 
H#define OUT_STRING_PRECIS 
Hdefine OUTLCHARACTER_PRECIS 
#define OUT_STROKE_PRECIS 


Hdefine CLIP_DEFAULT_PRECIS 
Hdefine CLIP_CHARACTER_PRECIS 
#define CLIP_STROKE_PRECIS 


Hdefine DEFAULT_QUALITY 
#define DRAFT_QUALITY 
#define PROOF_QUALITY 


H#define DEFAULT_PITCH 
Adefine FIXED_PITCH 
Hdefine VARIABLE_PITCH 


#define ANSI_CHARSET 
#define SYMBOL_CHARSET 
#define SHIFTJIS_CHARSET 
#define OEM_CHARSET 


/* Font Families */ 
H#define FF_DONTCARE 


(0<<4) 


LETTE; 


*PLOGFONT; 


NT; 
NT; 


N= oO WN- Oo 


N= oO 


N= 


0 
2 
128 
255 


/* Don't care or don't know. */ 
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#define FF_ROMAN (1<<4) /* Variable stroke width, serifed. */ 
/* Times Roman, Century Schoolbook, etc. */ 

#define FF_SWISS (2<<4) /* Variable stroke width, sans-serifed. */ 
/* Helvetica, Swiss, etc. */ 

H#define FF_MODERN (3<<4) /* Constant stroke width, serifed or sans-serifed. */ 
/* Pica, Elite, Courier, etc. */ 

#define FF_SCRIPT (4<<4) /* Cursive, etc. */ 


Hdefine FF_DECORATIVE (5<<4) /* Old English, etc. */ 


/* Font Weights */ 


#define FW_DONTCARE 0 

#define FW_THIN 100 

Hdefine FW_EXTRALIGHT 200 

#define FW_LIGHT 300 

#define FW_NORMAL 400 

H#define FW_MEDIUM 500 

#define FW_SEMIBOLD 600 

H#define FW_BOLD 700 

#define FW_EXTRABOLD 800 

#define FW_HEAVY 900 

H#define FW_ULTRALIGHT FW_EXTRALIGHT 
Hdetine FW_REGULAR FW_NORMAL 
#define FW_DEMIBOLD FW_SEMIBOLD 
#define FW_ULTRABOLD FW_EXTRABOLD 
#define FW_BLACK FW_HEAVY 

/* EnumFonts Masks */ 

H#define RASTER_FONTTYPE 0x0001 
H#define DEVICE_FONTTYPE 0x000e - 
#define SCALABLE_FONTTYPE 0x0004 
#define RGB(r,g,b) ‘CCDWORD) CC CBYTE) Cr) | CCWORD) (g)<<8) ) | CC CDWORD) (BYTE) (Cb) )<<16) )) 


H#define PALETTERGB(r,g,b) (Ox02000000 | RGB(r,g,b)) 
H#define PALETTEINDEXCi1) CCDWORD)(0x071000000 | (WORD) (i))) 


H#define GetRValue(rgb) (C(BYTE)(rgb)) 
Hdefine GetGValue(rgb) (CBYTE)(CCWORD) (rgb)) >> 8)) 
Hdefine GetBValue(rgb) (CBYTE)((rgb)>>16)) 


/* Background Modes */ 
#define TRANSPARENT 1 
#define OPAQUE 


/* Mapping Modes */ 
#define MM_TEXT 
#define MM_LOMETRIC 
#define MM_HIMETRIC 
#define MM_LOENGLISH 
#define MM_HIENGLISH 
#define MM_TWIPS 
#define MM_ISOTROPIC 
#define MM_ANISOTROPIC 


AONAUEWN- 


/* Coordinate Modes */ 
#define ABSOLUTE 
#define RELATIVE 


Na 


/* Stock Logical Objects */ 
#define WHITE_BRUSH 0 
#define LTGRAY_BRUSH 1 
#define GRAY_BRUSH 2 
#define DKGRAY_BRUSH 3 
#define BLACK_BRUSH 4 
#define NULL_BRUSH 5 
H#define HULLOW_BRUSH N 
#define WHITE_PEN 6 
#define BLACK_PEN 7 
H#define NULL_PEN 8 


ULL_BRUSH 
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define OEM_FIXED_FONT 
Hdefine ANSI_FIXED_FONT 


#define ANSI_VAR_FONT 
#define SYSTEM_FONT 


‘Adefine DEVICE_DEFAULT_FONT 14 - 
define DEFAULT_PALETTE 


define SYSTEM_FIXED_FONT 16 


/* Brush Styles */ 
#define BS_SOLID | 
H#define BS_NULL 
#define BS_HOLLOW 
#define BS_HATCHED 
Hdefine BS_PATTERN 
Hdefine BS_INDEXED 
#define BS_DIBPATTERN 


/* Hatch Styles */ 
Adefine HS_HORIZONTAL 
define HS_VERTICAL 
#define HS_FDIAGONAL 
#define HS_BDIAGONAL 
Hdefine HS_CROSS 


. Adefine HS_DIAGCROSS 


~ 


- /* Pen Styles */ 


#define PS_SOLID 
#define PS_DASH 
#define PS_DOT 

#define PS_DASHDOT 
H#define PS_DASHDOTDOT 
Hdefine PS_NULL 
#define PS_INSIDEFRAME 


/* Device Parameters for 


define DRIVERVERSION 
define TECHNOLOGY 
#define HORZSIZE 
define VERTSIZE 
H#define HORZRES 
#define VERTRES 
#define BITSPIXEL 
#define PLANES 
Hdefine NUMBRUSHES 
#define NUMPENS 
H#define NUMMARKERS 
define NUMFONTS 
H#define NUMCOLORS 
H#define PDEVICESIZE 
#define CURVECAPS 
H#define LINECAPS 
H#define POLYGONALCAPS 
#define TEXTCAPS 
#define CLIPCAPS 
Hdefine RASTERCAPS 
Hdefine ASPECTX 
Hdefine ASPECTY 
#define ASPECTXY 


#define LOGPIXELSX 
H#define LOGPIXELSY 


#define SIZEPALETTE 
define NUMRESERVED 
Hdefine COLORRES 


#ifndef NOGDICAPMASKS 


S_NULL 


MPSWN Do 


EEL */ 
JENANNA */ 
*/ 
1* +4444 */ 
/*® xXxxxx */ 


WUPWnN=o 

~ 

* 
~ 
~ 
~ 
~ 
~ 


0 
1 
2 
3 EPs eee ee 
4 
5 
6 


GetDeviceCaps() */ 

0) * Device driver version 

2 /* Device classification 

4 /* Horizontal size in millimeters 
6 /* Vertical size in millimeters 


8 /* Horizontal width in pixels 

10 /* Vertical width in pixels 

12 /* Number of bits per pixel 

14 /* Number of planes 

16 /* Number of brushes the device has 
18 /* Number of pens the device has 

20 /* Number of markers the d@vice has 
22 /* Number of fonts the device has 

24 /* Number of colors the device supports 
26 /* Size required for device descriptor 
28 /* Curve capabilities , 

30 /* Line capabilities 

32 /* Polygonal capabilities 

34 /* Text capabilities 

36 /* Clipping capabilities 

38 /* Bitblt capabilities 

40 /* Length of the X leg 

42 /* Length of the Y leg 

44 /* Length of the hypotenuse 

88 /* Logical pixels/inch in X 

90 /* Logical pixels/inch in Y 

104 /* Number of entries in physical palette 
106 /* Number of reserved entries in- palette 


108 /* Actual color resolution 


/* Device Capability Masks: */ 


/* Device Technologies */ 


#define DT_PLOTTER 
#define DT_RASDISPLAY 
#define DT_RASPRINTER 
#define DT_RASCAMERA 
#define DT_CHARSTREAM 
#define DT_METAFILE 
Adefine DT_DISPFILE 


/* Curve Capabilities */ 
#define CC_NONE 

Hdefine CC_CIRCLES 
#define CC_PIE 

#define CC_CHORD 
Hdefine CC_ELLIPSES 
H#define CC_WIDE 

#define CC_STYLED 
H#define CC_WIDESTYLED 
H#define CC_INTERIORS 


/* Line Capabilities */ 
#define LC_NONE 
H#define LC_POLYLINE 
Hdefine LC_MARKER 
4#define LC_POLYMARKER 
Hdefine LC_WIDE ° 
Hdefine LC_STYLED 
H#define LC_WIDESTYLED 
H#define LC_INTERIORS 


AuSWN =O 


32 
64° 
128 


8 
16 
32 
64 
128 


/* Polygonal Capabilities */ 


#define PC_NONE 

#define PC_POLYGON : 
#define PC_RECTANGLE 
H#define PC_WINDPOLYGON 
H#define PC_TRAPEZOID 
#define PC_SCANLINE 
Hdefine PC_WIDE 

#define PC_STYLED 
#define PC_WIDESTYLED 
#define PC_INTERIORS 


#define CP_NONE 
#define CP_RECTANGLE 


/* Text Capabilities */ 
#define TC_OP_CHARACTER 
#define TC_OP_STROKE 
H#define TC_CP_STROKE 
#define TC_CR_90 
-#define TC_CR_ANY 
#define TC_SF_X_YINDEP 
#define TC_SA_DOUBLE 
#define TC_SA_INTEGER 
H#define TC_SA_CONTIN 
define TC_EA_DOUBLE 
#define TC_IA_ABLE 
#define TC_UA_ABLE 
#define TC_SO_ABLE 
#define TC_RA_ABLE 
define TC_VA_ABLE 
#define TC_RESERVED 


0 
; 
2 
4 
4 
8 
16 
32 


64 
128 


" /* Polygonal Capabilities */ 


0 
1 


0x0001 
0x0002 
0x0004 
0x0008 
0x0010 
0x0020 
0x0040 
0x0080 
0x0100 
0x0200 
0x0400 
0x0800 
0x1000 
0x2000 
0x4000 
0x8000 


#endif /* NOGDICAPMASKS */ 


Vector plotter 

Raster display 

Raster printer 

Raster camera 
Character-stream, PLP 
Metafile, VDM 
Display-file 


Curves not supported <-~... ~ 


Can do circles 

Can do pie wedges 

Can do chord arcs 

Can do ellipese 

Can do wide Lines 

Can do styled Lines 
Can do wide styled Lines 
Can do interiors 


Lines not supported 

Can do polylines 

Can do markers 

Can do polymarkers 

Can do wide lines 

Can do styled Lines 

Can do wide styled Lines 
Can do interiors 


Polygonals not supported 
Can do polygons 

Can do rectangles 

Can do winding polygons 
Can do trapezoids 

Can do scanlines 

Can do wide borders 

Can do styled borders 


Can do wide styled borders 


Can do interiors 


No clipping of output 
Output clipped to rects 


Can do OutputPrecision 
Can do OutputPrecision 
Can do ClipPrecision 
Can do CharRotAbility 
Can do CharRotAbility 
Can do ScaleFreedom 

Can do ScaleAbility 

Can do ScaleAbility 

Can do ScaleAbility 

Can do EmboldenAbility 
Can do ItalisizeAbility 
Can do UnderlineAbility 
Can do StrikeQutAbility 
Can do RasterFontAble 
Can do VectorFontAble 
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CHARACTER 
STROKE 
STROKE 

90 

ANY 
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X_YINDEPENDENT */ 


DOUBLE 
INTEGER 
CONTINUOUS 
DOUBLE 
ABLE 

ABLE 

ABLE 

ABLE 

ABLE 


WINDOWS API BIBLE 


/* Raster Capabilities */ 


#define RC_BITBLT 1 
#define RC_BANDING 2 
#define RC_SCALING 4 
Hdefine RC_BITMAP64 8 


“#define RC_GDI20_OUTPUT 0x0010 
#define RC_DI_BITMAP 0x0080 


#define RC_PALETTE 0x0100 
#define RC_DIBTODEV 0x0200 
#define RC_BIGFONT 0x0400 


H#define RC_STRETCHBLT 0x0800 
H#define RC_FLOODFILL 0x1000 
Hdefine RC_STRETCHDIB 0x2000 


/* palette entry flags */ 

H#define PC_RESERVED 0x01 
Hdefine PC_EXPLICIT Qx02 
H#define PC_NOCOLLAPSE 0x04 


/* DIB color table identifiers */ 


Hdefine DIB_RGB_COLORS 0 
Hdefine DIB_PAL_COLORS 1 


/* Can do standard BLT. */ 
/* Device requires banding support */ 
/* Device requires scaling support */ 
/* Device can support >64K bitmap */ 


/* has 2.0 output cails */] 
/* supports DIB to memory */ 
/* supports a palette - */ 
/* supports DIBitsToDevice x] 
/* supports >64K fonts —- */ 
/* supports StretchBlt */ 
/* supports FloodFill */ 
/* supports: StretchDIBits *] 
/* palette index,used for animation *]- 
/* palette index is explicit to device x/ 


/* do not match color to system palette */ 


/* color table in RGBTriples */ 
/* color table in palette indices*/ 


/* constants for Get/SetSystemPaletteUse() */ . 


\ 
. Hdefine SYSPAL_STATIC 1 
\ #define SYSPAL_NOSTATIC 2 


/* constants for CreateDIBitmap */ 


#define CBM_INIT OxO04L 


» 


#ifndef NODRAWTEXT 


/* DrawText() Format Flags */. 
Adefine DT_TOP 

Hdefine DT_LEFT 

Hdefine DT_CENTER 

H#define DT_RIGHT 

H#define DT_VCENTER 

#define DT_BOTTOM 

#define DT_WORDBREAK 
#define DT_SINGLELINE 
H#define DT_EXPANDTABS 
#define DT_TABSTOP 

H#define DT_NOCLIP 

#define DT_EXTERNALLEADING 
#define DT_CALCRECT . 
H#define DT_NOPREFIX 
H#define DT_INTERNAL 


int API DrawTextCHDC, LPSTR, 


/* initialize bitmap */ 


0x0000 ‘ 
0x0000 
0x0001 
0x0002 
0x0004 
0x0008 
0x0010 
0x0020 
0x0040 
0x0080 
0x0100 
0x0200 
0x0400 
0x0800 . 
0x1000 


int, LPRECT, WORD); 


BOOL API DrawIcon(HOC, int, int, HICON); 


#endif /* NODRAWTEXT */ 


/* ExtFloodFill style flags */ 


#define FLOODFILLBORDER 0 

#define FLOODFILLSURFACE 1 

HDC API GetWindowDC(HWND); 

HDC API GetDC(HWND) ; 
int API ReleaseDCCHWND, HDC); | 


Hifdef WIN31 
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HDC API GetDCEx(Cregister HWND hwnd, HRGN hrgnClip, DWORD flags); 
/* GetDCEx(€) flags */. 

H#define DCX_WINDOW 0x00000001L 
H#define DCX_CACHE 0x00000002L 
Hdefine DCX_NORESETATTRS 0x00000004L 
H#define DCX_CLIPCHILDREN 0x00000008L 
#define DCX_CLIPSIBLINGS 0x00000010L 
Hdefine DCX_PARENTCLIP 0x00000020L 
Hdefine DCX_EXCLUDERGN O0xQ0000040L 
H#define DCX_INTERSECTRGN O0x00000089L 
H#define DCX_EXCLUDEUPDATE 0x00000100L 
H#define DCX_INTERSECTUPDATE 0x00000200L 


Adefine DCX_LOCKWINDOWUPDATE 0x00000400L 


H#define DCX_USESTYLE Qx00010000L 
#define DCX_NORECOMPUTE 0x00100000L 
#define DCX_VALIDATE 0x00200000L 


Hendif /* WIN31 */ 


HDC API CreateDC(LPSTR, LPSTR, LPSTR, LPVOID); 
HDC API CreateIC(LPSTR, LPSTR, LPSTR, LPVOID); 
HDC API CreateCompatibleDCCHDC); 

BOOL API DeleteDCCHDC); 

int API SaveDCCHDC); 


BOOL API RestoreDCCHDC, int); 
DWORD API MoveToCHDC, int, int); 
DWORD API GetCurrentPosition(HDC); 
BOOL API LineToCHDC, int, int); 
DWORD API GetDCOrg(HDC); 


int API MulDivCint, int, int); 

BOOL API ExtTextOut(HDC, int, int, WORD, LPRECT, LPSTR, WORD, LPINT); 
BOOL API PolylineCHDC, LPPOINT, int); 

BOOL API Polygon(HDC, LPPOINT, int); 

BOOL API PolyPolygon(HDC, LPFOINT, LPINT, int); 

BOOL API RectangleC(HDC, int, int, int, int); 


BOOL API RoundRectCHDC, int, int, int, int, int, int); 
BOOL API EllipseCHOC, int, int, int, int); 


BOOL API ArcCHDC, int, int, int, int, int, int, int, int); 
BOOL API ChordCHDC, int, int, int, int, int, int, int, int); 
BOOL API PieC(HDC, int, int, int, int, int, int, int, int); 


BOOL API PatBLtC(HDC, int, int, int, int, DWORD); 

BOOL API BitBLt(HDC, int, int, int, int, HDC, int, int, DWORD); 
BOOL API StretchBltCHDC, int, int, int, int, HDC, int, int, int, int, DWORD); 
BOOL API TextOutCHDC, int, int, LPSTR, int); 

LONG API TabbedTextOut(HDC, int, int, LPSTR, int, int, LPINT, nts 
BOOL API GetCharWidthC(HDC, WORD, WORD, LPINT); 

DWORD API SetPixel( HDC, int, int, DWORD); 

DWORD API GetPixel( HDC, int, int); 

BOOL API FloodFill¢€ HDC, int, int, DWORD); 

BOOL API ExtFloodFillCHDC, int, int, DWORD, WORD); 

void API LineDDACint, int, int, int, FARPROC, LPSTR); 


HANDLE API GetStockObject(int); 


HPEN API CreatePenCint, int, DWORD); 
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HPEN API CreatePenIndirect(LOGPEN FAR *);., 0 , 6 30 7 po he 

HBRUSH API CreateSolidBrush{DWORD) ; ; 

HBRUSH API CreateHatchBrushCint,DWORD); . en ae : gies of Sa 
DWORD API SetBrushOrg(HDC, int, int); - ae Pea 
DWORD API GetBrushOrg(HDC); 

HBRUSH API CreatePatternBrushCHBITMAP) ; 


HBRUSH API CreateBrushIndirect (LOGBRUSH FAR *); bbe fe ie calle 


HBITMAP API CreateBitmapCint, int, BYTE, BYTE, LPSTR); 7 
HBITMAP API CreateBitmapIndirect(BITMAP FAR *); : vfs 
HBITMAP API CreateCompatibleBitmapC(HDC, int, int); mi 7 oe 
HBITMAP API CreateDiscardableBitmap(HDC, int, int); 


LONG API SetBitmapBitsCHBITMAP, DWORD, LPSTR); 

LONG API GetBitmapBits(HBITMAP, LONG, LPSTR); 

DWORD API SetBitmapDimension(HBITMAP, int, int); ° 1 
* DWORD API GetBitmapDimension(HBITMAP) ; 


HFONT API CreateFont(int, int, int, int, int, BYTE, BYTE, BYTE, BYTE, BYTE, BYTE, BYTE, : 
BYTE, LPSTR); ‘i pete 4 ; 
HFONT API CreateFontIndirect(LOGFONT FAR *); 


int’ API SelectClipRgnCHDC, HRGN); 

HRGN API CreateRectRgn(int, int, int, int); 

void API SetRectRgnCHRGN, int, int, int, int); 

HRGN API CreateRectRgnindirect(LPRECT); 

HRGN API CreateEllipticRgnIindirect(LPRECT); 

HRGN API CreateEllipticRgn(int, int, int, int);. 

HRGN API CreatePolygonRgn(LPPOINT, int, int); 

HRGN API CreatePolyPolygonRgn(LPPOINT, LPINT, int, int); 
HRGN API CreateRoundRectRgn(int, int, int, int, int, int); 


BOOL API IsGDIObject (HANDLE); 


int API GetObject(HANDLE, int, LPVOID); 
BOOL API DeleteObject CHANDLE); 

HANDLE API SelectObject(HDC, HANDLE); 
BOOL API UnrealizeObject (HBRUSH); 


DWORD API SetBkColor(CHDC, DWORD); 

DWORD API GetBkColorCHDC); | 

int API SetBkModeC(HDC, int); 

int API GetBkMode(HDC); ‘, 
DWORD API SetTextColor(HDC, DWORD); : 2 
-DWORD API GetTextColor(CHDC); . ; 
WORD. API SetTextAlign(HDC, WORD); 

WORD API GetTextAlign(HDC); 

DWORD API SetMapperFlagsCHDC, DWORD); 

DWORD API GetAspectRatioFilter (HDC); 

DWORD API GetNearestColor(HDC, DWORD); ‘ 


- int API SetROP2CHDC, int); 
int API GetROP2CHDC); 
int API SetStretchBltModeCHDC, int); 
int~--- - API GetStretchBLtMode(HDC); 
int API SetPolyFillModeCHDC, int); 
int: API GetPolyFillModeCHDC); 
int API SetMapModeC(HDC, int); 
int API GetMapModeCHDC); 


DWORD ~- API SetWindowOrg(HDC, int, int); 

DWORD API GetWindowOrg(HDC); 

DWORD API SetWindowExtCHDC, int, int); 

DWORD API«GetWindowExt (HDC); 

DWORD API SetViewportOrg(HDC, int; int); 

DWORD API GetViewportOrg(HDC); 

DWORD API SetViewportExtCHDC, int, int); 

DWORD API GetViewportExtCHDC); 

DWORD API OffsetViewportOrgC(HDC, int, int); 

DWORD API ScaleViewportExtC(HDC, int, int, int, int); 
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DWORD 
DWORD 


int 
int 
int 
int 
BOOL 
int 
BOOL 
int 
int 


API OffsetWindowOrg(HDC, int, int); 
API ScaleWindowExt(HDC, int, int, int, int); 


API GetClipBox (HDC, LPRECT); 

API IntersectClipRect(HDC, int, int, Ants ais 
API OffsetClLipRgnC(HDC, int, int); ; 

API ExcludeClipRect(HDC, int, int, int, int); 
API PtVisibleCHDC, int, int); 

API CombineRgnCHRGN, HRGN, HRGN, int); 

API EqualRgn(HRGN, HRGN); 

API OffsetRgn(HRGN, int, int); 

API GetRgnBox(HRGN,: LPRECT); 


Hifdef WIN31 


/* Drawing bounds accumulation APIs */ 


WORD 
WORD 


#define 
#define 
#define 
H#define 
#define 
#define 


Hendif 


int 
OWORD 
DWORD 
int 
int 


API SetBoundsRect(HDC hDC, LPRECT LpreBounds, WORD flags); 
API GetBoundsRect (HDC hDC, LPRECT LprcBounds, WORD flags); 


DCB_RESET 0x0001 

DCB_ACCUMULATE 0x0002 re 
DCB_DIRTY DCB_ACCUMULATE 

DCB_SET (DCB_RESET | DCB_ACCUMULATE) 
DCB_ENABLE 0x0004 

DCB_DISABLE 0x0008 

/* WIN31 */ 


API SetTextJustification(HDC, int, int); 

API GetTextExtent(HDC, LPSTR, int); 

API GetTabbedTextExtent(HDC, LPSTR, int, int, LPINT); 
API SetTextCharacterExtra(HDC, int); 

API GetTextCharacterExtra(HDC); 


#ifdef WIN31 


DWORD 
Hendif 


HANDLE 
BOOL 
HANDLE 


Hifndef 
void 
BOOL 
Hendif 


BOOL 
int 
int 
int 
int 
int 


Hifndef 
BOOL 
#endif 
int 

int 

int 
BOOL 
BOOL 


HANDLE 
HANDLE 


API GetTextExtentEx(HDC, LPSTR, int, int, LPINT, LPINT); 
/* WIN31 */ 


API GetMetaFile(LPSTR); 
API DeleteMetaFileCHANDLE); 
API CopyMetaFileCHANDLE, LPSTR); 


NOMETAFILE 


API PlayMetaFileRecord(HDC, LPHANDLETABLE, LPMcTARECORD, WORD); 


API EnumMetaFile(HDC, LOCALHANDLE, FARPROC, BYTE FAR *); 


API PlayMetaFileC(HDC, HANDLE); 

API EscapeCHDC, int, int, LPSTR, LPSTR); 

API EnumFontsCHDC, LPSTR, FARPROC, LPSTR); 

API EnumFontFamiliesCHDC, LPSTR, FARPROC, LPSTR); 
API EnumObjects(HDC, int, FARPROC, LPSTR); 

API GetTextFace(HDC, int, LPSTR); 


NOTEXTMETRIC 
API GetTextMetricsCHDC, LPTEXTMETRIC ); 
API GetDeviceCaps(HDC, int); 


API SetEnvironment(LPSTR, LPSTR, WORD); 
API GetEnvironment(LPSTR, LPSTR, WORD); °° 


API DPtoLPCHDC, LPPOINT, int); 
API LPtoDPC(HDC, LPPOINT, int); 


API CreateMetaFile(LPSTR); 
API CloseMetaFileCHANDLE); 
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HANDLE API GetMetaFileBitsCHANDLE); 
HANDLE API-SetMetaFileBits (HANDLE); 


int. API SetDIBitsC(HDC,HANDLE,WORD,WORD,LPSTR,LPBITMAPINFO,WORD); 

‘int API GetDIBitsCHDC,HANDLE,WORD,WORD,LPSTR,LPBITMAPINFO,WORD) ; 

int API SetDIBitsToDevice(HDC,WORD,WORD,WORD,WORD, 
WORD,WORD,WORD,WORD, 


LPSTR,LPBITMAPINFO,WORD); 


HBITMAP API CreateDIBitmap(HDC,LPBITMAPINFOHEADER,DWORD,LPSTR, 


LPBITMAPINFO,WORD); 
HBRUSH API CreateDIBPatternBrushCHANDLE,WORD); 
int API StretchDIBits(HDC, WORD, WORD, WORD, WORD, WORD, 


WORD, WORD, WORD, LPSTR, LPBITMAPINFO, WORD, DWORD); 


HPALETTE API 
HPALETTE API 
WORD API 
int API 
void API 
WORD API 
WORD API 


CreatePalette (LPLOGPALETTE); 

SelectPalette (HDC,HPALETTE, BOOL?) ; 

RealizePalette CHDC) ; 

UpdateColors CHDC) ; 

AnimatePalette(HPALETTE, WORD, WORD, LPPALETTEENTRY); 
SetPaletteEntries(HPALETTE, WORD,WORD, LPPALETTEENTRY); 
GetPaletteEntries(HPALETTE ,WORD,WORD,LPPALETTEENTRY) ; 


WORD API GetNearestPaletteIndex(HPALETTE, DWORD); 
BOOL API ResizePalette(HPALETTE, WORD); ; 


WORD API GetSystemPaletteEntriesCHDC,WORD,WORD,LPPALETTEENTRY) 


WORD API GetSystemPaletteUseCHDC); 
WORD API SetSystemPaletteUse(HDC, WORD); 


#ifndef NOSCALABLEFONT 
/* GDI scalable font API prototypes and data structures: */ 


typedef struct _PANOSE ( /* panose */ 
BYTE bFamilyType; 
BYTE bSerifStyle; 
BYTE bWeight; 
BYTE bProportion; 
BYTE bContrast; 
BYTE bStrokeVariation; 
BYTE bArmStyle; 
BYTE bLetterform; 
BYTE bMidline; — 
BYTE bXHeight; 
} PANOSE; 


Hifndef NOTEXTMETRIC 


typedef struct CUTE TNE TES INE TREE { 


WORD otmSize; 

TEXTMETRIC otatexthat cies 
BYTE otmFiller; 

PANOSE otmPanoseNumber; 
WORD otmfsSelection; — 
WORD otmfsType; ~ 

WORD otmsCharSlopeRise; 
WORD otmsCharSlopeRun; 
WORD. otmEMSquare; 

WORD otmAscent; 

WORD otmDescent; 

WORD otmLineGap; 

WORD otmCapEmHeight; 
WORD otmXHeight; 

RECT otmrcFontBox; 

WORD otmMacAscent; 

WORD otmMacDescent; 

WORD otmMacLineGap; _ 
WORD otmusMinimumPPEM; 
POINTotmptSubscriptSize; 
POINTotmptSubscriptOffset; 


/* I size of this structure 

/* regular text metrics 

/* want to be word aligned 

/* Panose number of font 

/* B Font selection flags (see #defines) 
/* B Type indicators (see #defines) 

/* Slope angle Rise / Run 1 vertical 


/* 0 vertical 

/* N size of EM ; 

/* D ascent above baseline 

/* D descent below baseline 

/*® D 

/* D height of upper case M 

/* D height of lower case chars in font 
/* D Font bounding box 

/* D ascent above baseline for Mac 
/* >b descent below baseline for Mac.: 
/* D Minimum point ppem 

/* D Size of subscript 

/* D Offset of subscript 
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POINTotmptSuperscriptSize; 
POINTotmptSuperscriptOffset; 
WORD otmsStrikeoutSize; 
WORD otmsStrikeoutPosition; 
WORD otmsUnderscoreSize; 
WORD otmsUnderscorePosition; 
PSTR otmpFamilyName; 
PSTR otmpFaceName; 
PSTR otmpStyleName; 
PSTR otmpFullName; 

} OUTLINETEXTMETRIC; 


typedef OUTLINETEXTMETRIC 
Hendif /* NOTEXTMETRIC */ 
typedef struct _FIXED ¢ 
WORD fract; 
short value; 
} FIXED; 
typedef struct _MAT2 ¢{ 
FIXED eM11; 
FIXED eM12; 
FIXED eM2i; 
FIXED eM22; 
} MAT2; 
typedef MAT2 
typedef struct _GLYPHMETRICS ¢ 
WORD gmBlackBoxX; 
WORD gmBlackBoxY; 
POINT gmptGlyphOrigin; 
short gmCellIncXx; 
short gmCellIncY;. 
+ GLYPHMETRICS; 
typedef GLYPHMETRICS 
typedef struct _ABC { 
short abcA; 
WORD abcB; 
short abcC; 
+ ABC; 
typedef ABC 
typedef WORD 


typedef struct 


short nSize; 
short — wFlags; 
short nLanguagelID; 


} RASTERIZER_STATUS; 


typedef RASTERIZER_STATUS 


/* offset to family name 

/* offset to face name 

/* offset to Style string 

/* offset to full name 

FAR *LPOUTLINETEXTMETRIC; 
FAR *LPHAT2; 

FAR | *LPGLYPHHETRICS; 

FAR *LPABC; 

FAR *LPFONTDIR; 


FAR 


D Size of superscript 

D Offset of superscript 
D Strikeout size 

D Strikeout position 

D Underscore size 

D Underscore position 


—RASTERIZER_STATUS € 


*LPRASTERIZER_STATUS; 


/* bits defined in wFlags of. RASTERIZER_STATUS */ 


#define TT_AVAILABLE 
#define TT_ENABLED 


0x0001 
0x0002 


DWORD API ConvertOutlineFontFile(LPSTR, LPSTR, LPSTR); 
DWORD API GetFontDataCHDC, DWORD, DWORD, LPSTR, DWORD); 


DWORD API GetGlyphOutlineCHDC, WORD, WORD, LPGLYPHMETRICS, DWORD, LPSTR, LPMAT2); 


DWORD API EngineMakeFontDirCHDC, LPFONTDIR, LPSTR); 


BOOL API CreateScalableFontResource(HDC, LPSTR, LPSTR, LPSTR); 


BOOL API GetCharABCWidthsCHDC, WORD, WORD, LPABC); 
BOOL ~ API. GetRasterizerCaps(LPRASTERIZER_STATUS, int); 
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. Hifndef NOTEXTMETRIC 
DWORD API GetOutlineTextMetrics(HDC, WORD, LPOUTLINETEXTMETRIC); 
#endif /* NOTEXTMETRIC */ = 


Hendif /* NOSCALABLEFONT */ 
Hendif /* NOGDI */ 


Do a a ES i a */ 
/* USER Section */ 
[SB nmemen nce nnn newer neon eee nner enn wen */ 


#ifndef NOUSER 
int API wvsprintf(LPSTR,LPSTR,LPSTR); 
‘#ifdef _ cplusplus 

extern "C" 

£ 

Hendif /* __cplusplus */ 

int FAR cdecl wsprintf(LPSTR,LPSTR,...);7 
#ifdef __ cplusplus 

} 

Hendif /* _ cplusplus */ 
#ifndef NOSCROLL 

/* Scrolt Bar Constants */ 
Adefine SB_HORZ 

#define SB_VERT 

#define SB_CTL 

#define SB_BOTH 

define SB_MAX 

#define ESB_ENABLE_BOTH 
#define ESB_DISABLE_LTUP 


A#define ESB_DISABLE_RTDN 
#define ESB_DISABLE_BOTH 


Ww WN Oo Ww WUN=06 


Hdefine ESB_MAX 


/* Scroll Bar Commands */ 
H#define SB_LINEUP 
#define SB_LINEDOWN 
H#define SB_PAGEUP 
#define SB_PAGEDOWN 
Hdefine SB_THUMBPOSITION 
Hdefine SB_THUMBTRACK 
#define SB_TOP 

#define SB_BOTTOM 
#define SB_ENDSCROLL 


ANAUSWN=O 


#endif /* NOSCROLL */ — 
#ifndef NOSHOWWINDOW 


/* ShowWindow() Commands */_ 
A#define SW_HIDE 
‘#define SW_SHOWNORMAL 
Adefine SW_NORMAL 

#define SW_SHOWMINIMIZED 
H#define SW_SHOWMAXIMIZED 


WN 320 
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_Hdefine SW_MAXIMIZE 
H#define SW_SHOWNOACTIVAT 
#define SW_SHOW 
#define SW_MINIMIZE 
H#define SW_SHOWMINNOACTI 
#define SW_SHOWNA 
#define SW_RESTORE 


E 


VE 


OONAU EW 


/* Old ShowWindow() Commands */ 


H#define HIDE_WINDOW 

H#define SHOW_OPENWINDOW 
H#define SHOW_ICONWINDOW 
H#define SHOW_FULLSCREEN 


H#define SHOW_OPENNOACTIVATE 


0 
1 
2 
3 
4 


/* Identifiers for the WM_SHOWWINDOW message */ 


Adefine SW_PARENTCLOSING 
H#define SW_OTHERZOOM 
#define SW_PARENTOPENING 
d#define SW_OTHERUNZOOM 


#endif /* NOSHOWWINDOW */ 


/* Region Flags */ 
#define ERROR 

define NULLREGION 
#define SIMPLEREGION 
H#define COMPLEXREGION 


WN 206 


/* CombineRgn() Styles */ 


Hdefine RGN_AND 
#define RGN_OR 

#define RGN_XOR 
H#define RGN_DIFF 
H#define RGN_COPY 


#ifndef NOVIRTUALKEYCODE 


MFWAN = 


s 


SWN = 


/* Virtual Keys, Standard Set */ 


#define VK_LBUTTON 
t#define VK_RBUTTON 
H#define VK_CANCEL 
#define VK_MBUTTON 
#define VK_BACK 
Hdefine VK_TAB 
#define VK_CLEAR 
#define VK_RETURN 
#define VK_SHIFT 
#define VK_CONTROL 
#define VK_MENU 
#define VK_PAUSE 
Hdefine VK_CAPITAL 
H#define VK_ESCAPE 
define VK_SPACE 
Hdefine VK_PRIOR 
Hdefine VK_NEXT 
H#define VK_END 
#define VK_HOME 
#define VK_LEFT 
H#define VK_UP 
#define VK_RIGHT 
4define VK_DOWN 
Adefine VK_SELECT 
#define VK_PRINT 
#define VK_EXECUTE 
#define VK_SNAPSHOT 
/* d#define VK_COPY 
#define VK_INSERT 


0x01 
0x02 
0x03 
0x04 


0x08 


0x09 
QxOc 


- OxOD 


0x10 
Ox11 
Ox12 
0x13 
Ox14 
Ox1B 
0x20 
0x21 
Ox22 
Ox23 
0x24 
0x25 
0x26 
Ox27 
0x28 
0x29 
Ox2A 


0x28 


Ox2c 
Ox2c 
Ox2D 


/* NOT contiguous with L & RBUTTON */ 


not used by keyboards. */ 
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#define VK_DELETE Ox2E 
#define VK_HELP Ox2F 


/* VK_A thru VK_Z are the same as their ASCII equivalents: 'A' thru 'Z' */ 
/* VK_O thru VK_9 are the same as their ASCII equivalents: 'O' thru 'O' */ 


#define VK_NUMPADO 0x60 
#define VK_NUMPAD1 0x61 
#define VK_NUMPAD2 0x62 
#define VK_NUMPAD3 0x63 
#define VK_NUMPAD4 0x64 
#define VK_NUMPADS 0x65 
H#define VK_NUMPAD6 0x66 
#define VK_NUMPAD7 0x67 
H#define VK_NUMPADS . 0x68 
#define VK_NUMPAD9 0x69 
#define VK_MULTIPLY Ox6A 
#define VK_ADD 0x6B 
#define VK_SEPARATOR 0x6c 
#define VK_SUBTRACT Ox6D 
#define VK_DECIMAL Ox6E 
#define VK_DIVIDE Ox6F 
#define VK_F1 0x70 
4define VK_F2 0x71 
#define VK_F3 0x72 
#define VK_F4 0x73. 
#define VK_F5 0x74 
#define VK_F6 0x75 
#define VK_F7 0x76 
#define VK_F8 0x77 
Adefine VK_F9 0x78 
Adefine VK_F10 0x79 
#define VK_F11 Ox7A 
Hdefine VK_F12 0x7B 
Adefine VK_F13 Ox7C 
Hdefine VK_F14 Ox7D 
Hdefine VK_F15 Ox7E 
H#define VK_F16 Ox7F 
4#define VK_NUMLOCK ~ 0x90 
#define VK_SCROLL 0x91 


Hendif /* NOVIRTUALKEYCODES */ 


typedef struct tagWNDCLASS 
{ 


WORD style; 

LONG CAPI *LpfnWndProc)(CHWND, unsigned, WORD, LONG); 

int cbClsExtra; 

int cbWndExtra; 

HANDLE hInstance; 

HICON hIcon; 

HCURSOR hCursor; 

HBRUSH hbrBackground; 

LPSTR lpszMenuName; 

LPSTR lpszClassName; 

} WNDCLASS; 

typedef WNDCLASS *PWNDCLASS; 
typedef WNDCLASS NEAR *NPWNDCLASS; 
typedef WNDCLASS FAR *LPWNDCLASS; 


#ifndef NOMSG 


/* Message structure */ 
typedef struct tagMSG 
{ ‘i 


HWND hwnd; 
WORD message; 
WORD wParam; 
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LONG lParam; 
DWORD time; 
POINT pt; 
} MSG; : 
typedef MSG *PMSG; 


typedef MSG NEAR *NPMSG; 
typedef MSG FAR *LPMSS; 


Hendif /* NOMSG */ 


Hifndef NOWINOFFSETS 


/* Window field offsets for GetWindowLong() and GetWindowWord() */ 


H#define GWL_WNDPROC - 
H#define GWW_HINSTANCE 
#define GWW_HWNDPARENT 
Hdefine GWwW_ID 

H#define GWL_STYLE 
#define GWL_EXSTYLE 


/* Class field offsets for GetClassLong() and GetClassWord() */ 


#define GCL_MENUNAME 
adefine GCW_HBRBACKGROUND 
define GCW_HCURSOR 
#define GCW_HICON 

#define GCW_HMODULE 
H#define GCW_CBWNDEXTRA 
#define GCW_CBCLSEXTRA 
H#define GCL_WNDPROC 
H#define GCW_STYLE 


Hendif /* NOWINOFFSETS */ 
#ifndef NOWINMESSAGES 


/* Window Messages */ 
#define WM_NULL 

#define WM_CREATE 
#define WM_DESTROY 
define WM_MOVE 

#define WM_SIZE 

H#define WM_ACTIVATE 
H#define WM_SETFOCUS 
#define WM_KILLFOCUS 
#define WM_ENABLE 
Adefine WM_SETREDRAW 
#define WM_SETTEXT 
#define WM_GETTEXT 
H#define WM_GETTEXTLENGTH 
#define WM_PAINT- 
#define WM_CLOSE 

H#define WM_QUERYENDSESSION 
H#define WM_QUIT. 

H#define WM_QUERYOPEN 
define WM_ERASEBKGND 
#define WM_SYSCOLORCHANGE 
H#define WM_ENDSESSION 
#define WM_SHOWWINDOW 
H#define WM_CTLCOLOR 
H#define WM_WININICHANGE 
#define WM_DEVMODECHANGE 
#define WM_ACTIVATEAPP 
#define WM_FONTCHANGE 
#define WM_TIMECHANGE 
#define WM_CANCELMODE 
#define WM_SETCURSOR 
#define WM_MOUSEACTIVATE 
#define WM_CHILDACTIVATE 


(-4) 
(-6) 
(-8) 
(-12) 
(-16) 
(-20) 


(-8) 

(-10) 
(-12) 
(-14) 
(-16) 
(-18) 
(-20) 
(-24) 
(-26) 


0x0000 
.0x0001 
0x0002 
0x0003 
0x0005 
0x0006 
0x0007 
0x0008 
OxO000A 
0x000B 
oxdo0c 
0x000D 
OxOO0E 
OxO00F 
0x0010 
0x0011 
0x0012 
0x0013 
0x0014 
0x0015 
0x0016 
0x0018 
0x0019 
OxO001A 


0x001B 


0x001C 
0x001D 
OxO01E 
0x001F 
0x0020 
0x0021 
0x0022 
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WINDOWS API BIBLE _ 


#define 
#define 
#define 
#define 
#define 
Hdefine 
#define 
#define 
#define 
Hdefine 
H#define 
#define 
#define 
#define 
Hdefine 
Hdefine 


#define 
Hdefine 


#define 


#define WM_WINDOWPOSCHANGING 
Hdefine WM_WINDOWPOSCHANGED 


#define 


WM_QUEUESYNC 
WM_GETMINMAXINFO 
WM_PAINTICON 
WM_ICONERASEBKGND 
WM_NEXTDLGCTL 
WM_SPOOLERSTATUS 
WM_DRAWITEM 
WM_MEASUREITEM 
WM_DELETEITEM 
WM_VKEYTOITEM 
WM_CHARTOITEM 
WM_SETFONT 
WM_GETFONT 
WM_SETHOTKEY 
WM_GETHOTKEY 
WM_QUERYDRAGICON 


WM_COMPAREITEM 
WM_COMPACTING 


' Hifdef WIN31 
#define WM_OTHERWINDOWCREATED 
H#define WM_OTHERWINDOWDESTROYED 


WM_COMMNOTIFY 


WM_POWER 


Hendif /* WIN31 */ 


Hdefine 
#define 
Hdefine 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
H#define 


#define 
#define 
#define 
#define 
H#define 
H#define 
#define 
Hdefine 
#define 
#define 


#define 
#define 
H#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


WM_NCCREATE 
WM_NCDESTROY 
WM_NCCALCSIZE 
WM_NCHITTEST 
WM_NCPAINT 
WM_NCACTIVATE 
WM_GETDLGCODE 
WM_NCMOUSEMOVE ~ . 
WM_NCLBUTTONDOWN 
WM_NCLBUTTONUP 
WM_NCLBUTTONDBLCLK 
WM_NCRBUTTONDOWN 
WM_NCRBUTTONUP 
WM_NCRBUTTONDBLCLK 
WM_NCMBUTTONDOWN 
WM_NCMBUTTONUP 
WM_NCMBUTTONDBLCLK 


WM_KEYFIRST 
WM_KEYDOWN 
WM_KEYUP 
WM_CHAR 
WM_DEADCHAR 
WM_SYSKEYDOWN . 
WM_SYSKEYUP 
WM_SYSCHAR 
WM_SYSDEADCHAR 
WM_KEYLAST 


WM_INITDIALOG 
WM_COMMAND 
WM_SYSCOMMAND 
WM_TIMER 
WM_HSCROLL 
WM_VSCROLL 
WM_INITMENU 
WM_INITMENUPOPUP 
WM_MENUSELECT 
WM_MENUCHAR 


0x0023 
0x0024 
0x0026 
0x0027 
0x0028 
Ox002A 
0x0028 
0x002C 
0x002D 
Ox002E 
0x002F 
0x0030 


-:0x0031 


0x0032 
0x0033 
0x0037 


0x0039 
0x0041 


0x0042 
0x0043 
0x0044 


0x0046 
0x0047 
0x0048 


0x0081 
0x0082 
0x0083 
0x0084 
0x0085 
0x0086 
0x0087 
0x00A0 


“Ox00A1 


Ox00A2 
Ox00A3 
Ox00A4 
Ox00A5 
OxQ0A6 
Ox00A7 
Ox00A8 
Ox00A9 


0x0100 
0x0100 
0x0101 
0x0102 
0x0103 
0x0104 
0x0105 
0x0106 
0x0107 
0x0108 


0x0110 
0x0111 
0x0112 


~ 0x0113 


0x0114 
0x0115 
0x0116 
0x0117 
Ox011F 
0x0120 
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#define WM_ENTERIDLE 0x0121 
H#define WM_MOUSEFIRST. | 0x0200 
H#define WM_MOUSEMOVE 0x0200 
define WM_LBUTTONDOWN 0x0201 
H#define WM_LBUTTONUP 0x0202 
#define WM_LBUTTONDBLCLK 0x0203 
#define WM_RBUTTONDOWN 0x0204 
#define WMH_RBUTTONUP 0x0205 
#define WM_RBUTTONDBLCLK 0x0206 
#define WM_MBUTTONDOWN 0x0207 
#define WM_MBUTTONUP 0x0208 
H#define WM_MBUTTONDBLCLK 0x0209 
H#define WM_MOUSELAST 0x0209 
H#define WM_PARENTNOTIFY 0x0210 
#define WM_MDICREATE 0x0220 
#define WM_MDIDESTROY 0x0221 
#define WM_MDIACTIVATE Ox0222 
#define WM_MDIRESTORE Ox0223 
#define WM_MDINEXT Ox0224 
#define WM_MDIMAXIMIZE 0x0225 
_H#define WM_MDITILE 0x0226 
#define WM_MDICASCADE 0x0227 
#define WM_MDIICONARRANGE 0x0228 
Hdefine WM_MDIGETACTIVE 0x0229 
H#define WM_MDISETMENU 0x0230 
#define WM_DROPFILES 0x0233 
#define WM_CUT ; 0x0300 
H#define WM_COPY 0x0301 
#define WM_PASTE 0x0302 
#define WM_CLEAR 0x0303 
#define WM_UNDO 0x0304 
H#define WM_RENDERFORMAT 0x0305 
_#define WM_RENDERALLFORMATS 0x0306 
#define WM_DESTROYCLIPBOARD 0x0307 
#define WM_DRAWCLIPBOARD 0x0308 
#define WM_PAINTCLIPBOARD 0x0309 
#define WM_VSCROLLCLIPBOARD Ox030A 
#define WM_SIZECLIPBOARD 0x030B 
#define WM_ASKCBFORMATNAME 0x030C 
#define WM_CHANGECBCHAIN 0x030D 
#define WM_HSCROLLCLIPBOARD Ox030E 
#define WM_QUERYNEWPALETTE Ox030F 
#define WM_PALETTEISCHANGING 0x0310 
H#define WM_PALETTECHANGED 0x0311 
Hifdef WIN31 
#define WM_PENWINFIRST 0x0380 
#define WM_PENWINLAST Ox038F 
H#define WM_COALESCE_FIRST 0x0390 
#define WM_COALESCE_LAST 0x039F 


#endif /* WIN31 */ 


/* NOTE: ALL Message Numbers below 0x0400 are RESERVED. */ 


/* Private Window Messages Start Here: */ 
#define WM_USER 0x0400 


of WM_SIZE message wParam values */ 
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Hdefine SIZENORMAL 
#define SIZEICONIC 
#define SIZEFULLSCREEN 
Hdefine SIZEZOOMSHOW 
#define SIZEZOOMHIDE 


FWN=0 


Hifdef WIN31 


/7* WM_WINDOWPOSCHANGING/CHANGED struct pointed to by lParam */ 
typedef struct tagWINDOWPOS 
{ 


HWND hwnd; 

HWND hwndInsertAfter; 
int x; 

int y; 

int cx; 

int cy; 


WORD flags; 
} WINDOWPOS; 
typedef WINDOWPOS FAR *LPWINDOWPOS; 


Hendif /* WIN31 */ - 
“Hifndef NONCMESSAGES 


/* WM_SYNCTASK Commands */ - 
#define ST_BEGINSWP 0 
#define ST_ENDSWP 1 


/* WinWhere() Area Codes */ 
#define HTERROR (-2) 
Hdefine HTTRANSPARENT (-1) 
Hdefine HTNOWHERE 
define HTCLIENT 
#detine HTCAPTION 
#define HTSYSMENU 
#define HTGROWBOX 
#define HTSIZE 
#define HTMENU 
H#define HTHSCROLL 
define HTVSCROLL 
H#define HTREDUCE . 
#define HTZOOM 
#define HTLEFT 10 
#define HTRIGHT 
#define HTTOP 12 
#define HTTOPLEFT 13 
H#define HTTOPRIGHT 14 
#define HTBOTTOM 15 
#define HTBOTTOMLEFT 16 
#define HTBOTTOMRIGHT 17 


TGROWBOX 


WANAUZEWN=O0 


_ 
— 


#ifdef WIN31 


/* WM_NCCALCSIZE parameter structure */ 
typedef struct tagNCCALCSIZE_PARAMS 
C 


RECT rgrcl3J; 
WINDOWPOS FAR* Lppos; 
} NCCALCSIZE_PARAMS; 
typedef NCCALCSIZE_PARAMS FAR* LPNCCALCSIZE_PARAMS; 


/* WM_! NCCALCSIZE “window valid rect" return values *t 
#define WVR_ALIGNTOP 0x0010 
Hdefine WVR_ALIGNLEFT 0x0020 
Hdefine WVR_ALIGNBOTTOM 0x0040 
#define WVR_ALIGNRIGHT 0x0080 
#define WVR_HREDRAW 0x0100 
#define WVR_VREDRAW 0x0200 
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CWVR_HREDRAW | WVR_VREDRAW) 


Hdefine WVR_REDRAW 

H#define WVR_VALIDRECTS 0x0400 

Hendif /* WIN31 */ 

Hendif /* NONCMESSAGES */ 

/* WM_MOUSEACTIVATE Return Codes */ 
#define MA_ACTIVATE 1 
#define MA_ACTIVATEANDEAT 2 
Hdefine MA_NOACTIVATE 3 
Hifdef WIN31 

H#define MA_NOACTIVATEANDEAT 4 
Hendif /* WIN31 */ 

WORD API RegisterWindowMessage(LPSTR); 
Hifndef NOKEYSTATES . 

/* Key State Masks for Mouse Messages */ 
#define MK_LBUTTON 0x0001 

#define MK_RBUTTON 0x0002 

#define MK_SHIFT 0x0004 

#define MK_CONTROL 0x0008 

H#define MK_MBUTTON 0x0010. 


Hendif /* NOKEYSTATES */ 


Hendif /* NOWINMESSAGES */ 


#ifndef 


NOWINSTYLES 


“/* Window Styles */ 


H#define 
Hdefine 
define 
#define 
#define 
#define 
#define 
H#define 
#define 
H#define 
#define 
#define 
#define 
H#define 
#define 
#define 
#define 
#define 


#define 
#define 


#define 
#define 
#define 


WS_OVERLAPPED 
WS_POPUP 
WS_CHILD 
WS_MINIMIZE 
WS_VISIBLE 
WS_DISABLED 
WS_CLIPSIBLINGS 
WS_CLIPCHILDREN 
WS_MAXIMIZE 
WS_CAPTION 
WS_BORDER 
WS_DLGFRAME 
WS_VSCROLL 
WS_HSCROLL 
WS_SYSMENU 
WS_THICKFRAME 
WS_GROUP 
WS_TABSTOP 


WS_MINIMIZEBOX 
WS_MAXIMIZEBOX 


WS_TILED 
WS_ICONIC 
WS_SIZEBOX 


Ox00000000L 
Ox80000000L 
Ox40000000L 
Ox20000000L 
0x10000000L 
Ox08000000L 
0x04000000L 
0x02000000L 
0x01000000L 
Ox00CO0000L 
Ox00800000L 
0x00400000L 
Ox00200000L 
0x00100000L 
0x00080000L 
0x00040000L 
0x00020000L 
0x00070000L 


0x00020000L 
0x00010000L 


WS_OVERLAPPED 
WS_MINIMIZE 
WS_THICKFRAME 


/* Common Window Styles */ 
WS_OVERLAPPEDWINDOW (WS_OVERLAPPED | WS_CAPTION | WS_SYSMENU | WS_THICKFRAME | 
WS_MINIMIZEBOX | WS_MAXIMIZEBOX) 

CWS_POPUP | WS_ BORDER | WS_SYSMENU) 


#define 


#define 
d#define 


define 


WS_POPUPWINDOW 
WS_CHILDWINDOW 


WS_TILEDWINDOW 


(WS_CHILD) 


/* WS_BORDER | WS_DLGFRAME */ 


C(WS_OVERLAPPEDWINDOW) 


‘/* Extended Window Styles */ 
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Hdefine WS_EX_DLGMODALFRAME 0x00000001L 
#define WS_EX_NOPARENTNOTIFY 0x00000004L 


Hifdef WIN31 


#define WS_EX_TOPMOST 0xo0000008L 
define WS_EX_ACCEPTFILES 0x00000010L 
Hdefine WS_EX_TRANSPARENT 0x00000020L 


Hendif /* WIN31 */ 


/* Class styles */ 


#define CS_VREDRAW 0x0001 
#define CS_HREDRAW 0x0002 
Hdefine CS_KEYCVTWINDOW . 0x0004 
Hdefine CS_DBLCTLKS yon cous 
define CS_OWNDC | 0x0020 
. Hdefine CS_CLASSDC 0x0040 
Hdefine CS_PARENTDC 0x0080 
#define CS_NOKEYCVT 0x0100 
#define CS_NOCLOSE 0x0200 
#define CS_SAVEBITS 0x0800 
H#define CS_BYTEALIGNCLIENT . 0x1000 
#define CS_BYTEALIGNWINDOW 0x2000 
Hdefine CS_GLOBALCLASS | 0x4000 /* Global window class */ 


Hendif /* NOWINSTYLES */ 
#ifndef NOCLIPBOARD 


/* Predefined Clipboard Formats */ 


#define CF_TEXT 1 

#define CF_BITMAP 2 

#define CF_METAFILEPICT 3 

#define CF_SYLK 4 

#define CF_DIF 5 

/#define CF_TIFF 6 

#define CF_OEMTEXT 7 

#define CF_DIB 8 

#define CF_PALETTE 9 

#define CF_PENDATA 10 

#define CF_OWNERDISPLAY 0x0080 

#define CF_DSPTEXT 0x0081 

#define CF_DSPBITMAP 0x0082 

#define CF_DSPMETAFILEPICT 0x0083 

/* "Private" formats don't get GlobalFree()'d */ 

#define CF_PRIVATEFIRST 0x0200 

#define CF_PRIVATELAST OxO2FF 

/* "GDIOBJ" formats do get DeleteObject()'d */ 
_ Adefine CF_GDIOBJFIRST 0x0300 

‘#define CF_GDIOBJLAST OxO3FF 


Hendif /* NOCLIPBOARD */ 
typedef struct tagPAINTSTRUCT 
{ 


HDC hdc; 

BOOL fErase; 

RECT rcPaint; 

BOOL fRestore; 

BOOL fIncUpdate; 

BYTE rgbReserved£16]; 
} PAINTSTRUCT; 
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typedef PAINTSTRUCT *PPAINTSTRUCT; 
typedef PAINTSTRUCT NEAR *NPPAINTSTRUCT; 
typedef PAINTSTRUCT FAR *LPPAINTSTRUCT; 


typedef struct tagCREATESTRUCT 


{ 
LPSTR LpCreateParams; 
HANDLE hInstance; 
HANDLE hMenu; 
HWND hwndParent; 
int cy; 
int CX; 
int x2 
int xs. 
LONG style; 
LPSTR LpszName; 
LPSTR lpszClass; 
DWORD dwExStyle; 


} CREATESTRUCT; 
typedef CREATESTRUCT FAR *LPCREATESTRUCT; 


/* Owner draw control types */ 
Hdefine ODT_MENU 1 
H#define ODT_LISTBOX 2 
H#define ODT_COMBOBOX 3 
Hdefine ODT_BUTTON 4 


/* Owner draw actions */ 

Hdefine ODA_DRAWENTIRE 0Ox0001 
#define ODA_SELECT 0x0002 
H#define GDA_FOCUS 0x0004 


/* Owner draw state */ 
H#define ODS SELECTED 0x0001 


H#define ODS_GRAYED 0x0002 
#define ODS_DISABLED 0x0004 
#define ODS CHECKED 0x0008 
Hdefine ODS_FOCUS 0x0010 


/* MEASUREITEMSTRUCT for ownerdraw */ . 
typedef struct tagMEASUREITEMSTRUCT . . 
C 


WORD ctlType; 
WORD Ctlibd; 

WORD ' .4temlo; 
WORD itemWidth; 
WORD itemHeight; 
DWORD itemData; 


} MEASUREITEMSTRUCT; ‘ : 
typedef MEASUREITEMSTRUCT NEAR *PMEASUREITEMSTRUCT; 
typedef MEASUREITEMSTRUCT FAR *LPMEASUREITEMSTRUCT; 


/* DRAWITEMSTRUCT for ownerdraw */ 
typedef struct tagDRAWITEMNSTRUCT 


{ 
WORD CtlType; 
WORD ctlid; 
WORD itemID; 
WORD itemAction; 
WORD itemState; 
HWND hundIitem; 
HDC ; hDC; 
RECT reItem; 
DWORD itemData; 
} DRAWITEMSTRUCT; : 
typedef DRAWITEMSTRUCT NEAR *PDRAWITEMSTRUCT; 
typedef DRAWITEMSTRUCT FAR *LPDRAWITEMSTRUCT; 


977 


WINDOWS API BIBLE 


/* DELETEITEMSTRUCT for ownerdraw */ 
typedef struct tagDELETEITEMSTRUCT 
{ 


WORD CtlType; 
WORD | Ctlib; 
WORD itemID; 
HWND ~ hwndIitem; 
OWORD itemData; 


} DELETEITEMSTRUCT; 
typedef DELETEITEMSTRUCT NEAR *PDELETEITEMSTRUCT; 
typedef DELETEITEMSTRUCT FAR *LPDELETEITEMSTRUCT; 


/* COMPAREITEMSTUCT fos ownerdraw sorting */ 
typedef struct tagCOMPAREITEMSTRUCT 
{ 


WORD CtlType; 
WORD Ctliod; 

“ HWND . hwnditem; 
WORD itemIDi; 
DWORD itemDatat; 
WORD itemID2; 

' OWORD itemData2; 


_ > COMPAREITEMSTRUCT; : 
typedef COMPAREITEMSTRUCT NEAR *PCOMPAREITEMSTRUCT; 
typedef COMPAREITEMSTRUCT FAR *LPCOMPAREITEMSTRUCT; 


#ifndef NOMSG 


/* Message Function Templates */ j 

BOOL APT GetMessage(LPMSG, HWND, WORD, WORD); 

BOOL API TranslateMessage(LPMSG) > 

LONG _API DispatchMessage(LPMSG); 

BOOL API PeekMessage(LPMSG, HWND, WORD, WORD, WORD); 


/* PeekMessage() Options */ 


#define PM_NOREMOVE 0x0000 
Adefine PM_REMOVE 0x0001 
Hdefine PM_NOYIELD 0x0002 


Hendif /* NOMSG */ 


#ifndef NOLSTRING 
int API Lstrcmp( LPSTR, LPSTR ); 
int API Ltstreapi( LPSTR, LPSTR >; 
LPSTR API Lstrcpy( LPSTR, LPSTR ); 
LPSTR API (Ustrcat( LPSTR, LPSTR ); 
int API Ustrlen( LPSTR ); 
fendif /* NOLSTRING */ 


#ifndef NOLFILEIO 


int API _lopen(€ LPSTR, int ); 
int API _(close( int ); 
int API _lcreat( LPSTR, int ); 


LONG API _Ulseek( int, long, int ); 
WORD API _lread( int, LPSTR, int ); 
WORD API _lwrite( int, LPSTR, int ) 


#define READ OQ /* Flags for _lopen */ 
#define WRITE 1 
define READ_WRITE 2 


Hendif /* NOLFILEIO */ 


BOOL API ExitWindows(DWORD dwReturnCode, WORD wReserved); 


H#define EWLRESTARTWINDOWS | Ox42 
#ifdef WIN31 
#define EW_REBOOTSYSTEM “0x43 


#endif /* WIN31 */ 
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BOOL API SwapMouseButton(BOOL); 
DWORD API GetMessagePos(void); 
LONG API GetMessageTime(void); 


#ifdef WIN31 
LONG API GetMessageExtralInfo (void); 
Hendif /* WIN31 */ 


HWND API GetSysModalWindow(void); 
HWND API SetSysModal Window CHWND) > 


LONG API SendMessage(HWND, WORD, WORD, LONG); 

BOOL API PostMessage(HWND, WORD, WORD, LONG); 

BOOL API PostAppMessageCHANDLE, WORD, WORD, LONG); 

void API ReplyMessage(LONG); 

void API WaitMessage(void); 

LONG API DefWindowProcC(HWND, WORD, WORD, LONG); 

void API PostQuitMessageCint);> 

LONG API CallWindowProcCFARPROC, HWND, WORD, WORD, LONG); 
BOOL APL InSendMessage(void); 


WORD API GetDoubleClickTime(void); 
void API SetDoubleClickTime(WORD); 


BOOL API RegisterClass(LPWNDCLASS); : 
BOOL API UnregisterClass(LPSTR, HANDLE); - 
BOOL API GetClassInfoCHANDLE, LPSTR, LPWNDCLASS); 


BOOL API SetMessageQueuelint); 


H#define CW_USEDEFAULT €Cint)0x8000) 

HWND API CreateWindowC(LPSTR, LPSTR, DWORD, int, int, int, int, HWND, HMENU, HANDLE, LPSTR); 
HWND API CreateWindowEx(DWORD, LPSTR, LPSTR, DWORD, int, int, int, int, HWND, HMENU, HANDLE, 
LPSTR); 


BOOL API IsWindow(CHWND) ; ay he 
BOOL API IsChildCHWND, HWND); , 
-BOOL API DestroyWindow(HWND) ; Pa Mai 


BOOL API ShowWindowCHWND, int); 
BOOL API FlashWindowCHWND, BOOL); 
void APY ShowOwnedPopups(CHWND, BOOL); 


BOOL API OpenIconCHWND) ; 

void CloseWindowCHWND) ; 

void API MoveWindow(HWND, int, int, int, int, BOOL); 

void API SetWindowPosCHWND, HWND, int, int, int, int, WORD); 


#ifndef NODEFERWINDOWPOS 


HANDLE API BeginDeferWindowPosCint nNumWindows) ; 

HANDLE API DeferWindowPos (HANDLE hWinPosInfo, HWND hWnd, HWND hWndInsertAfter, int x, int y, 
int cx, int cy, WORD wFlags); 

void API EndDeferWindowPosCHANDLE hWinPosInfo); 


Wendif /* NODEFERWINDOWPOS */ 


BOOL API IsWindowVisibleCHWND) ; 
BOOL API IsIconicCHWND); 
BOOL API AnyPopup(void); 
void API BringWindowToTopCHWND) ; 
BOOL API IsZoomed(CHWND); 


/* Special HWND values for SetWindowPos() hundinsertAtter «/ 
#define HWND_TOP CCHWND NULL) 

#define HWND_BOTTOM . - CCHWND)1) 

#define HWND_GROUPTOTOP ((CHWND)-1) 


/* SetWindowPos() and WINDOWPOS flags */ 
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Hdefine 
#define 
#define 
#define 
#define 
#define 
_ define 
#define 
#define 
#define 


Hdefine 
Hdefine 


#ifndef 


HWND 
HWND 
HWND 
HWND 
int 
int 
int 
int 
void 
HWND 
void 
WORD 
void 
int 
void 
void 
WORD 
LONG 
HWND 
HWND 
int 
long 
LONG 
#define 


fendif 
#ifndef 
BOOL 
#endif 


Hifndef 


SWP_NOSIZE 0x0001 


SWP_NOMOVE 0x0002 

SWP_NOZORDER 0x0004 

SWP_NOREDRAW 0x0008 

SWP_NOACTIVATE .0x0010 

SWP_FRAMECHANGED 0x0020 /* The frame changed: send WM_NCCALCSIZE */ 
SWP_SHOWWINDOW Qx0040 - a 
SWP_HIDEWINDOW 0x0080 

SWP_NOCOPYBITS 0x0100 

SWP_NOOWNERZORDER 0x0200 /* Don't do owner Z ordering */ 
SWP_DRAWFRAME SWP_FRAMECHANGED 

SWP_NOREPOSITION SWP_NOOWNERZORDER 

NOCTLMGR 


API CreateDialog(HANDLE, LPSTR, HWND, FARPROC); 

API CreateDialogIndirect (HANDLE, LPSTR, HWND, FARPROC); 

API CreateDialogParamCHANDLE, LPSTR, HWND, FARPROC, LONG); 

API CreateDialogIndirectParamC(HANDLE, LPSTR, HWND, FARPROC, LONG); 
API DialogBox(HANDLE, LPSTR, HWND, FARPROC); 

API DialogBoxIndirect (HANDLE, HANDLE, HWND, FARPROC); — 

API DialogBoxParamC(HANDLE, LPSTR, HWND, FARPROC, LONG); 

API DialogBoxindirectParamCHANDLE, HANDLE, HWND, FARPROC, LONG); 


‘API EndDialogCHWND, int); 


API GetDlgItemCHWND, int); 

API SetDlgItemIntCHWND, int, WORD, BOOL); 

API GetDlgItemIntCHWND, int, BOOL FAR *, BOOL); 
API SetDlgItemText(HWND, int, LPSTR); 

API GetDlgItemTextC(HWND, int, LPSTR, int); 

API CheckDlgButtonCHWND, int, WORD); 

API CheckRadioButton(HWND, int, int, int); 

API. IsDlgButtonChecked(HWND, int); 

API SendDlgItemMessage(HWND, int, WORD, WORD, LONG); 
API GetNextDlgGroupItemCHWND, HWND, BOOL); 

API GetNextDlgTabItem(CHWND, ae BOOL); 


‘API GetDLgCtrlIDCHWND); 


API GetDialogBaseUnits(void); 
API DefDlgProcC(HWND, WORD, WORD, LONG); 


DLGWINDOWEXTRA 30 /* Window extra byted needed for private. dialog classes */ 


/* NOCTLMGR */ 


NOMSG 
API CallMsgFilter(LPMSG, int); 


NOCLIPBOARD 


/* Clipboard Manager Functions */ 


BOOL 
BOOL 


API OpenClipboard(HWND) ; 
API CloseClipboard(void); 


-Hifdef WIN31 ~- 


HWND 
flendif 


HWND 
HWND 
HWND 
BOOL 
HANDLE 
HANDLE 
WORD 
int 
WORD 
int 


API GetOpenClipboardWindow(void) ; 
/* WIN31 */ i 


API GetClipboardOwner (void); 

API SetClipboardViewer (CHWND) ; 

APL GetClipboardViewer (void); ; 

AP1 .ChangeClipboardChainCHWND, HWND); 

API setClipboardDataCWORD, HANDLE); 

API GetClipboardDataCWORD); 

API RegisterClipboardFormat(LPSTR); 

API CountClipboardFormats(void); — 

API EnumClipboardFormats(WORD) ; 

API GetClipboardFormatName(WORD, LPSTR, int); 
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BOOL API EmptyClipboard(void); : 
BOOL API IsClipboardFormatAvailable(WORD); 
int API GetPriorityClipboardFormat(WORD FAR *, int); 


Hendif /* NOCLIPBOARD */ 


HWND API SetFocus(CHWND); 

HWND API GetFocus(void); 

HWND API GetActiveWindow(void); 

int API GetKeyState(int); 

int API GetAsyncKeyState(Cint); 

void API GetKeyboardState(BYTE FAR *); 
void API SetKeyboardState(BYTE FAR *); 
BOOL API EnableHardwareInput (BOOL); 
BOOL API GetInputState(void); 

HWND API GetCapture(void); 
HWND API SetCaptureCHWND); 
void API ReleaseCapture(void); 


> 


Hifdef WIN31 
DWORD API GetQueueStatus(WORD flags); 


/* GetQueueStatus flags */ 

Hdefine QS_KEY 0x0001 
#define QS_MOUSEMOVE 0x0002 
#define QS_MOUSEBUTTON 0Qx0004 


H#define QS_MOUSE (QS_MOUSEMOVE | QS_MOUSEBUTTON) 
H#define QS_POSTMESSAGE 0x0008 
#define QS_TIMER 0x0010 
H#define Q@S_PAINT 0x0020 


#define QS_SENDMESSAGE 0x0040 


Hendif /* WIN31 */ 

/* Windows Functions */ 

WORD API SetTimerCHWND, int, WORD, FARPROC); 
BOOL API KitlTimerCHWND, int); 


BOOL API EnableWindowCHWND,BOOL) ; 
BOOL API IsWindowEnabled(CHWND) ; 


HANDLE API LoadAccelerators(HANDLE, LPSTR); 

Hifndef NOMSG 

int API TranslateAccelerator(HWND, HANDLE, LPMSG); 
Hendif 

#ifndef NOSYSMETRICS 


/* GetSystemMetrics() codes */ 


H#define SM_CXSCREEN 0 
#define SM_CYSCREEN 1 
#define SM_CXVSCROLL 2 
H#define SM_CYHSCROLL 3 
Hdefine SM_CYCAPTION 4 
#define SM_CXBORDER 5 
#define SM_CYBORDER 6 
A#define SM_CXDLGFRAME 7 
H#define SM_CYDLGFRAME 8 
#define SM_CYVTHUMB 9 
Hdefine SM_CXHTHUMB 10 
H#define SM_CXICON 11 
H#define SM_CYICON 12 
Hdefine SM_CXCURSOR 13 
#define SM_xCYCURSOR 14 
#define SM_CYMENU 15 


#define SM_CXFULLSCREEN 16: 
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ddefine SM_CYFULLSCREEN- - 17, 


Hdefine SM_CYKANJIWINDOW 18 
#define SM_MOUSEPRESENT 19 
Hdefine SM_CYVSCROLL - 20 - 
Hdefine SM_CXHSCROLL ° ~~~ 21 
H#define SM_DEBUG 22 
#define SM_SWAPBUTTON . 23 
Hdefine SM_RESERVED1 , 24 
H#define SM_RESERVED2 25 
H#define SM_RESERVED3 26 
H#define SM_RESERVED4 27 
#define SM_CXMIN . 28 
#define SM_CYMIN: 29 
H#define SM_CXSIZE 30 
. Hdefine SM_CYSIZE 31 
#define SM_CXFRAME 32 
define SM_CYFRAME : 33 
Adefine SM_CXMINTRACK 34 
_Adefine SM_CYMINTRACK ‘ 35 
#ifdef WIN31 . 
H#define SM_CXDOUBLECLK 36 
H#define SM_CYDOUBLECLK | 37 
4#define SM_CXICONSPACING 38 
H#define SM_CYICONSPACING 39 
#define SM_MENUDROPALIGNMENT 40 
4define SM_PENWINDOWS 41 


Hendif /* WIN31 */ 


int API GetSystemMetrics(int); 
Hendif /* NOSYSMETRICS */ 

#Hifndef NOMENUS 

BOOL API IsMenuCHMENU),; 


HMENU API LoadMenuCHANDLE, LPSTR); 

HMENU API LoadMenuIndirect(LPSTR); 

HMENU API GetMenuCHWND); 

BOOL API SetMenuCHWND, HMENU); 

BOOL API ChangeMenuCHMENU, WORD, LPSTR, WORD, WORD); 
BOOL API HiliteMenuItemCHWND, HMENU, WORD, WORD); 

int API GetMenuString(HMENU, WORD, LPSTR, int, WORD); 
WORD API GetMenuStateC(HMENU, WORD, WORD); 
void -API DrawMenuBar (HWND); 

HMENU. API GetSystemMenu(HWND, BOOL); 

HMENU API CreateMenu(void); 

HMENU API CreatePopupMenu( void); 

BOOL API DestroyMenu(HMENU) ; é 
BOOL API CheckMenultemC(HMENU, WORD, WORD); 
BOOL API EnableMenultemCHMENU, WORD, WORD); 
HMENU API GetSubMenuCHMENU, int); 

WORD API GetMenultemIDCHMENU, int); 

WORD API GetMenultemCount CHMENU); 


BOOL API InsertMenuCHMENU, WORD, WORD, WORD, LPSTR); 

BOOL API AppendMernuCHMENU, WORD, WORD, LPSTR); 

BOOL API nod fRequCMENU, WORD, WORD, WORD, LPSTR); 

BOOL API RemoveMenuCHMENU, WORD, WORD); 

-BOOL « API DeleteMenuCHMENU, WORD, WORD); 

BOOL API SetMenultemBitmaps (HMENU, WORD, WORD, HBITMAP, HBITMAP) ; 
“LONG © pra ge thenuchecklsrkeisenstanstvotd?) 


BOOL API TrackPopupMenuCHMENU, sities int, int, int, HWND, LPRECT); 
./* Flags for TrackPopupMeny */: 
H#define TPM_LEFTBUTTON 0x0000 


. Hifdef WIN31 


982 


#define 
Hdefine 
Hdefine 
#define 


TPH_RIGHTBUTTON 0x0002 
TPM_LEFTALIGN 0x0000 
TPM_CENTERALIGN 0x0004 
TPM_RIGHTALIGN 0x0008 


#endif /* WIN31 */ 


Hendif /* NOMENUS ad 


BOOL 
void 
HWND 


HDC 
void 
BOOL 
int 
int 


void 
void 


void 
void 


API GrayString(HDC, HBRUSH, FARPROC, OMORD, int, int, int, int, int); 
API UpdateWindowCHWND); 
API SetActiveWindowCHWND) > 


API BeginPaintCHWND, LPPAINTSTRUCT); 
API EndPaint(HWND, LPPAINTSTRUCT); 

API GetUpdateRect (HWND, LPRECT, BOOL); 
API GetUpdateRgn i HWND, HRGN, BOOL); 


API ExcludeUpdateRgn(HDC, HWND); 


API InvalidateRect(HWND, LPRECT, BOOL); 
API ValidateRectCHWND, LPRECT); 


API InvalidateRgn(HWND, HRGN, BOOL); 
API ValidateRgnCHWND, HRGN); 


Hifdef WIN31 


BOOL 


API RedrawWindow(CHWND hwnd, 
LPRECT LprcUpdate, HRGN hrgnUpdate, WORD flags); 


/* RedrawWindow() flags */ 


d#define 


' #define 


#define 
ddefine 
Adefine 
Adefine 


#define 


Hdefine 


#define 
#define 


RDW_INVALIDATE 0x0001 
ROW_INTERNALPAINT 0x0002 
RDW_ERASE -  0x0004 
\ 
RDW_VALIDATE - 0x0008 
RDW_NOINTERNALPAINT 0x0010 
RDW_NOERASE 0x0020 
RDW_NOCHILDREN 0x0040 
RDW_ALLCHILDREN 0x0080 
x 
RDW_UPDATENOW 0x0100 
RDW_ERASENOU 0x6200 


/* LockWindowUpdate API */ 
BOOL API LockWindowUpdate(HWND hwndLock); 


Hendif /* WIN31 */ 


void 
BOOL 


API ScrollWindow(HWND, int, int, LPRECT, LPRECT); 
API ScrollDCCHDC, int, int, LPRECT, LPRECT, HRGN, LPRECT); 


#ifdef WIN31 = 


int 


define 


API ScrollWindowEx( 
HWND hwnd, 

int dx, 

int dy, 

EPRECT prcScroll, 
LPRECT prcClip, 
HRGN hrgnUpdate, 
LPRECT prcUpdate, 
WORD flags); 


SW_SCROLLCHILDREN 0x0001 /* Scroll children within *lprcScroll. 
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#define SW_INVALIDATE Ox0002 /* Invalidate after scrolling */. 
wucfine SW_ERASE 0x0004 /* Tf SW_LINVALIDATE, don't send WM_ERASEBACKGROUND */ 


ee 
#endif /* WIN31 */ 


Hifndef NOSCROLL - 

int API SetScrolLPos(HWND, int, int, BOOL); 

int API GetScrollPos(HWND, int); 

void API SetScrollRangeCHWND, int, int, int, BOOL); 
void API GetScrollRangeCHWND, int, LPINT, LPINT); 
void API ShowScroltlBarCHWND, WORD, BOOL); 

BOOL API EnableScrollBarCHWND, WORD, WORD); 

Hendif 


BOOL API SetPropCHWND, LPSTR, HANDLE); 
HANDLE API GetProp(HWND, LPSTR); 
HANDLE API RemoveProp(HWND, LPSTR); 


int API EnumProps(HWND, FARPROC); 

void API SetWindowTextCHWND, LPSTR); 

int API GetWindowText(HWND, LPSTR, int); 
int API GetWindowTextLength(HWND); 


void API GetClientRect(HWND, LPRECT); 

void API GetWindowRect(HWND, LPRECT); 

void API AdjustWindowRect(LPRECT, LONG, BOOL); 

void API AdjustWindowRectEx(LPRECT, LONG, BOOL, DWORD); 


#ifndef NOMB 


/* MessageBox() Flags */ 


4define MB_OK 0x0000 

#define MB_OKCANCEL 0x0001 

#define MB_ABORTRETRYIGNORE 0x0002 

Hdefine MB_YESNOCANCEL 0x0003 

define MB_YESNO 0x0004 

#define MB_RETRYCANCEL 0x0005 

Hdefine MB_ICONHAND 0x0010 

define MB_ICONQUESTION — 0x0020 

#define MB_ICONEXCLAMATION 0x0030 

#define MB_ICONASTERISK 0x0040 

Hdefine MB_ICONINFORMATION MB_ICONASTERISK 
Hdefine MB_ICONSTOP MB_ICONHAND 
#define MB_DEFBUTTON1 0x0000 
Hidefine MB_DEFBUTTON2 0x0100 

#define MB_DEFBUTTON3 0x0200 

H#define MB_APPLMODAL ‘0x0000 

Hdefine M3_SYSTEMMODAL 0x1000 

Hdefine MB_TASKMODAL 0x2000 

#define MB_NOFOCUS 0x8000 

int APL MessageBox(HWND, LPSTR, Leste, WORD); 


void API MessageBeep(WORD); 
Hendif /* NOMB */ 


int API ShowCursor(BOOL); 
void API SetCursorPos(int, int); 


Hifdef WIN31 
‘-HCURSOR API GetCursor(void); 
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Hendif /* WIN31 */ 


HCURSOR API SetCursor(HCURSOR); 
void API GetCursorPos(LPPOINT); 
void API CLipCursor(LPRECT); 
Hifdef WIN31 

void API GetClipCursor(LPRECT); 
#endif 


void API CreateCaret(HWND, HBITMAP, int, int); 
WORD API GetCaretBlinkTime(void); 

void API SetCaretBlinkTimeCWORD) ; 

void API DestroyCaret (void); 

void API HideCaret (CHWND); 

void API ShowCaret(CHWND); 

void API SetCaretPosCint, int); 

void APT GetCaretPos(LPPOINT); 


void API ClientToScreenCHWND, LPPOINT); 
void API ScreenToClient(HWND, LPPOINT); 


Hitdef WIN3‘ 
void API MapWindowPointsCHWND hwndFrom, HWND hwndTo, LPPOINT Lppt, WORD cpt); 


H#define MapWindowRect(hwndFrom, hwndTo, lprc) \ 
MapWindowPointsChwndFrom, hundTo, (LPPOINT)&tpre, 2) 


Hendif /* WIN31 */ 


HWND API WindowFromPoint (POINT); 
HWND API ChiltdWindowFromPoint(HWND, POINT); 


#ifndef NOCOLOR 


/* Color Types */ 

#define CTLCOLOR_MSGBOX 
#define CTLCOLOR_EDIT 
#define CTLCOLOR_LISTBOX 
#define CTLCOLOR_BTN 
H#define CTLCOLOR_DLG 
Hdefine CTLCOLOR_SCROLLBAR 
#define CTLCOLOR_STATIC 
#define CTLCOLOR_MAX 


WDAUERWN-AO 


/* three bits max */ 


#define COLOR_SCROLLBAR 
H#define COLOR_BACKGROUND 
H#define COLOR_ACTIVECAPTION 
#define COLOR_INACTIVECAPTION 
#define COLOR_MENU 

H#define COLOR_WINDOW 
H#define COLOR_WINDOWFRAME 
#define COLOR_MENUTEXT 
Hdefine COLOR_WINDOWTEXT 
#define COLOR_CAPTIONTEXT 
#define COLOR_ACTIVEBORDER 10 . 
#define COLOR_INACTIVEBORDER 11 

H#define COLOR_APPWORKSPACE 12 

Hdefine COLOR_HIGHLIGHT 13 

#define COLOR_HIGHLIGHTTEXT 14 

#define COLOR_BTNFACE 15 

#define COLOR_BTNSHADOW 16 

Hdefine. COLOR_GRAYTEXT 17 

#define COLOR_BINTEXT 18. 

Hifdef WIN31 - 

H#define COLOR_INACTIVECAPTIONTEXT19 

#define COLOR_BTNHIGHLIGHT 20 

Hendif /* WIN31 ¥*/ 
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‘DWORD- 
void 


Hendif 


BOOL 
BOOL 
BOOL 
BOOL 
BOOL 


void 
int 

int 

void 
void 
void 
int 

void 
int 

int 

BOOL 
void 
BOOL 
BOOL 
BOOL 
BOOL 
BOOL 


DWORD 
DWORD 


API 
API 


GetSysColor(Cint); 
SetSysColorsCint, LPINT, LONG FAR *); 


/* NOCOLOR */ 


API 
API 
API 
API 
API 


API 
API 
API 
API 
API 
API 
API 
API 
API 
API 
API 
API 
API 
API 
API 
API 
API 


API 
API 


FilLLRgnC HDC, HRGN, HBRUSH); 
FrameRgnCHOC, HRGN, HBRUSH, int, int); 
InvertRgn(HDC, HRGN); 

PaintRgn(HDC, HRGN); 

PtInRegionCHRGN, int, int); 


DrawFocusRect (HDC, LPRECT); 

FillRect (HDC, LPRECT, HBRUSH); 
FrameRect(HDC, LPRECT, HBRUSH); 
InvertRect (HDC, LPRECT); 
SetRect(LPRECT, int, int, int, int); 
SetRectEmpty(LPRECT); 
CopyRect(LPRECT, LPRECT); 
InflateRect(LPRECT, int, int); 
IntersectRect(LPRECT, LPRECT, LPRECT); 
UnionRect(LPRECT, LPRECT, LPRECY); 
SubtractRect(LPRECT, LPRECT, LPRECT); 
OffsetRect(LPRECT, int, int); 
IsRectEmpty(LPRECT); 

EqualRect (LPRECT, LPRECT); 
PtInRect(LPRECT, POINT); 
RectVisibleC(HDC, LPRECT); 
RectInRegion(CHRGN, LPRECT); 


GetCurrentTime(void); 
GetTickCount (void); 


Hifndef NOWINOFFSETS 


WORD 
WORD 
LONG 
LONG 
WORD 
WORD 
LONG 
LONG 
HWND 
HWND 


Hendif 


. HWND 
HWND 
BOOL 
HWND 
BOOL 
BOOL. 
int 
HWND 
HWND 
HANDLE 
HWND 


API 
API 
API 
API 
API 
API 
API 
API 
API 
API 


GetWindowWord(HWND, int); 
SetWindowWord(HWND, int, WORD); 
GetWindowLong(HWND, int); 
SetWindowLongCHWND, int, LONG); 
GetClassWord(HWND, int); ; 
SetClassWord(HWND, int, WORD); 
GetClassLong(HWND, int); 
SetClassLong(HWND, int, LONG); 
GetDesktopHwnd(void); 
GetDesktopWindow(void); 


/* NOWINOFFSETS */ 


API 
API 
API 
API 
API 
API 
API 
API 
API 
API 
API 


GetParent CHWND); 

SetParent(HWND, HWND); 
EnumChildWindows(HWND, FARPROC, LONG); 
FindWindow(LPSTR, LPSTR); 
EnumWindows(CFARPROC, LONG); : 
EnumTaskWindows(HANDLE, FARPROC, LONG); 
GetClassNameCHWND, LPSTR, int); 

Get TopWindow(HWND); 
GetNextWindow(HWND, WORD); 
GetWindowTask(CHWND) ; 
GetLastActivePopupCHWND) ; 


/* GetWindow() Constants */ 
GW_HWNDFIRST 0 
GW_HWNDLAST 
GW_HWNDNEXT 


#define 
Hdefine 
Hdefine 
Hdefine 
H#define 


HWND 


GW_OWNER 
Hdefine GW_CHILD 


API 


1 
2 
GW_HWNOPREV 3 
4 
5 


GetWindowCHWND, WORD); 
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#ifndef NOWH 


FARPROC API SetWindowsHook(Cint, FARPROC); 
BOOL API UnhookWindowsHook( int, FARPROC); ; 
DWORD API DefHookProcCint, WORD, DWORD, FARPROC FAR *); 


#ifdef WIN31 


typedef DWORD HHOOK; 
typedef DWORD CAPI *HOOKPROC)Cint code, WORD wParam, LONG lParam); 


HHOOK API SetWindowsHookEx(int idHook, HOOKPROC Llpfn, HANDLE hModule, HANDLE hTask); 
BOOL API UnhookWindowsHookEx (HHOOK hHook); 
DWORD API Cal lNextHookEx(HHOOK hHook, int code, WORD wParam, LONG lParam); 


Hendif /* WIN31 */ 


/* SetWindowsHook() codes */ 

Hdefine WH _MSGFILTER ¢ 
#define WH_JOURNALRECORD 0 
Hdefine WH_JOURNALPLAYBACK 1 
#define WH_KEYBOARD 2 
#define WH_GETMESSAGE 3 
Hdefine WH_CALLWNDPROC 4 


Hifdef WIN31 \ 


ddefine WH_CBT 

#define WH _SYSMSGFILTER 
Hdefine WH MOUSE 
“#define WH_HARDWARE 
#define WH_DEBUG 


COONAN 


Hendif /* WIN31 */ 
_ /* Hook Codes */ 


#define HC_GETLPLPFN (~3) 
Adefine HC_LPLPFNNEXT (-2) 
H#define HC_LPFNNEXT (~1) 
define HC_ACTION 
H#define HC_GETNEXT 
#define HC_SKIP 
#define HC_NOREM 
H#define HC_NOREMOVE 
#define HC_SYSMODALON 
Hdefine HC_SYSMODALOFF 


UEUUN =O 


Hifdef WIN31 


/* CBT Hook Codes */ 
#define HCBT_MOVESIZE 
#define HCBT_MINMAX 
#define HCBT_QS 

#define HCBT_CREATEWND 
ddefine HCBT_DESTROYWND 
Hdefine HCBT_ACTIVATE 
#define HCBT_CLICKSKIPPED 
H#define HCBT_KEYSKIPPED —~ 
define HCBT_SYSCOMMAND 
H#define HCBT_SETFOCUS 


WOON AUS WN Oo 


/* HCBT_CREATEWND parameters pointed to by lParam */ 
typedef struct tagCBT_CREATEWND 
{ 


LPCREATESTRUCT  Ipes; 


HWND hundInsertAfter; 
) CBT_CREATEWND; 
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typedef CBT_CREATEWND FAR *LPCBT_CREATEWND; 
Hendif /* WIN31 */ 


/* WHUMSGFILTER Filter Proc Codes */ 
Hdefine MSGF_DIALOGBOX 0 
#define MSGF_MENU 2 
Hdefine MSGF_MOVE 3 
#define MSGF_SIZE 4. 
H#define MSGF_SCROLLBAR 5 
Hdefine MSGF_NEXTWINDOW 6 


/* Window Manager Hook Codes */ 


#define WC_INIT 1 
#define WC_SWP 2 
‘H#define WC_DEFWINDOWPROC3 
#define WC_MINMAX 4 
#define WC_MOVE 5 
#define WC_SIZE. 6 


Hdefine WC_DRAWCAPTION 7 


#ifdef WIN31 oo 
typedef struct tagMOUSEHOOKSTRUCT 


{ 
POINT pt; 
HWND hwnd; 
WORD wHitTestCode; 
DWORD dwExtralInfo; 


} MOUSEHOOKSTRUCT; 
typedef MOUSEHOOKSTRUCT FAR *LPMOUSEHOOKSTRUCT; 


typedef struct tagCBTACTIVATESTRUCT 
{ 
BOOL fMouse; 
HWND hWndActive; 
} CBTACTIVATESTRUCT; 


typedef struct tagHARDWAREHOOKSTRUCT 


{ 
HWND hWnd; 
WORD wMessage; 
WORD wParam; 


DWORD lParam; 
} HARDWAREHOOKSTRUCT, 


Hendif /* WIN3S1-*/ 


/* Message Structure used in Journaling */ 
typedef struct tagEVENTMSG 


{ 
WORD message; 
WORD paramL; 
WORD paramH; 
DWORD time; 
} EVENTMSG; 
typedef EVENTMSG *PEVENTMSGMSG,; — 
' typedef EVENTMSG NEAR *NPEVENTMSGMSG; 
typedef EVENTMSG FAR *LPEVENTMSGMSG; 


Hendif /* NOWH */ 
#ifndef NOMENUS 


#define MF_INSERT 0x0000 


#define MF_CHANGE 0x0080 
#de fine MF_APPEND 0x0100 


H#define MF_DELETE . _ 0x0200 
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0x1000 


/* Menu flags for Add/Check/EnableMenultem() */ 


#define MF_BYCOMMAND 
#define MF_BYPOSITION 


4#define MF_SEPARATOR 


Adefine MF._ENABLED 
#define MF_GRAYED 
define MF_DISABLED 


Adefine MF_UNCHECKED 
4#define MF_CHECKED 
#define MF_USECHECKBITMAPS 


#define MF_STRING 
#define MF_BITMAP 
4define MF_OWNERDRAW 


A#define MF_POPUPOx0010 
#define MF_MENUBARBREAK 
#define MF_MENUBREAK 


#define MF_UNHILITE 
#define MF_HILITE 


#define MF_SYSMENU 
#define MF_HELP 
H#define MF_MOUSESELECT 


/* Menu item resource format */ 


typedef struct 
t 
WORD versionNumber; 
WORD offset; 
} MENUITEMTEMPLATEHEADER; 


typedef struct 


{ 
WORD mtOption; 
WORD mtID; 
LPSTR mtString; 


} MENUITEMTEMPLATE; 
#define MF_END 
Hendif /* NOMENUS */ 
#ifndef NOSYSCOMMANDS 


/* System Menu Command Values */ 
#define SC_SIZE ~ 
#define SC_MOVE 

#define SC_MINIMIZE 

#define SC_MAXIMIZE 

H#define SC_NEXTWINDOW 

#define SC_PREVWINDOW 

#define SC_CLOSE 

#define SC_VSCROLL 

H#define SC_HSCROLL 

Hdefine SC_MOUSEMENU 

#define SC_KEYMENU 

#define SC_ARRANGE 

#define SC_RESTORE 

#define SC_TASKLIST 


0x0000 
0x0400 


0x0800 


0x0000 
0x0001 
0x0002 


0x0000 
0x0008 
0x0200 


0x0000 
0x0004 
0x0100 


0x0020 
0x0040 


0x0000 
0x0080 


0x2000 
0x4000 
0x8000 


0x0080 


OxF000 
OxFO010 
OxF020 
0xFO030 
OxF040 
OxFO050 
Ox F060 
OxFO070 
Ox F080 
Ox F090 
OxF100 
OxF110 
OxF120 
OxF130 
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H#define SC_SCREENSAVE OxF140 


| Adefine SC_HOTKEY OxF150 
#define SC_ICON SC_MINIMIZE 
Hdefine SC_Z00M SC_MAXIMIZE 


#endif /* NOSYSCOMMANDS */ 


/* Resource Loading Routines */ 

HBITMAP API LoadBitmapCHANDLE, LPSTR); 

HCURSOR API LoadCursor(HANDLE, LPSTR); 

HCURSOR API CreateCursor(HANDLE, int, int, int, int, LPSTR, LPSTR); 
~BOOL API DestroyCursor(CHCURSOR); 


/* Standard Cursor IDs */ 


H#define IDC_ARROW MAKE INTRESOURCE(32512) 
Adefine IDC_IBEAM MAKEINTRESOURCE (32513) 
H#define IDC_WAIT MAKEINTRESOURCE(32514) 
#define IDC_CROSS MAKEINTRESOURCE (32515) 
#define IDC_UPARROW MAKEINTRESOURCE (32516) 
H#define IDC_SIZE MAKEINTRESOURCE (32640) 
Hdefine ID0C_ICON MAKEINTRESOURCE (32641) 


H#define ILO0C_SIZENWSE MAKEINTRESOURCE (32642) 
Hdefine IDC_SIZENESW MAKEINTRESOURCE (32643) 
Hdefine IDC_SIZEWE MAKE INTRESOURCE( 32644) 
Adefine IDC_SIZENS MAKE INTRESOURCE(32645) 


HICON API LoadIcon(HANDLE, LPSTR); 
HICON API CreateIcon(HANDLE, int, int, BYTE, BYTE, LPSTR, LPSTR); 
BOOL API DestroyIconCHICON); 


- Hdefine ORD_LANGDRIVER 1 /* The ordinat number for the entry point of 
** Language drivers. 
*/ 


#ifndef NOICONS 


/* Standard Icon IDs */ 

H#define IDI_APPLICATION MAKEINTRESOURCE(32512) 
Adefine IDI_HAND MAKEINTRESOURCE(32513) 
define IDI_QUESTION MAKE INTRESOURCE(32514) 
Hdefine IDI_EXCLAMATION MAKEINTRESOURCE(32515) 
Hdefine IDI_LASTERISK , MAKEINTRESOURCE (32516) 


Wendit /* NOICONS “ay 
int API LoadString(HANDLE, WORD, LPSTR, int); 


int API AddFontResource(LPSTR); 
BOOL API RemoveFontResource({LPSTR); 


/* Dialog Box Command IDs */ 
define IDd0K 
define IDCANCEL 
Hdefine IDABORT 
Hdefine IDRETRY 
#define IDIGNORE 
#define IDYES 
#define IDNO 


NOUS WN = 


ifndef NOCTLMGR . 
/* Control Manager Structures and Definitions 7 
#Hifndef NOWINSTYLES 


/* Edit Control Styles */ 
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Hdefine 
Hdefine 
define 
Hdefine 
adefine 
fdefine 
ddefine 
#define 
Adefine 
define 
Hdefine 


Hifdef 
Hdefine 
Hendif 


Hendif 


/* Edit 
#define 
Hdetine 
Kdefine 
Hdefine 
Hdetine 
Hdefine 
ddefine 
#define 


#ifndef 


/* Edit 
idefine 
Adefine 
H#define 
#define 
#define 
H#define 
Hdefine 
Hdefine 
Hdefine 
Hdefine 
H#define 
Hidefine 
Sdefine 
#define 
Hdefine 
define 
tdefine 
Adefine 
adefine 
&define 
adefine 
H#define 
Hdefine 
H#define 
#define 
H#define 
adefine 


Hiftdef 
#define 
a#define 
#endif 
‘ Adefine 


#endif 


ES_LEFT 
ES_CENTER 
ES_RIGHT 
ES_HULTILINE 
ES UPPERCASE 
ES_LOWERCASE 
ES_PASSWORD 
ES_AUTOVSCROLL 
ES_AUTOHSCROLL 
ES_NOHIDESEL 
ES_OEMCONVERT 


WIN31 
ES_READONLY 
/* WIN31 */ 


Ox0000L 
Ox0001L 
0x0002L 
Ox0004L 
0x0008L 
0x0010L 
Ox0020L 
0x0040L 
0x0080L 
0x0100L 
0x0400L 


0x0800L 


/* NOWINSTTLES */ 


Control Notification Codes */ 


EN_SETFOCUS 
EN_KILLFOCUS 
EN_CHANGE 
EN_UPDATE 
EN_ERRSPACE 
EN_MAXTEXT 
EN_HSCROLL 
EN_VSCROLL 


NOWINMESSAGES 


0x0100 
0x6200 
0x0300 
0x0400 
0x0500- 
0x0501 
0x0601 
0x0602 


Control Messages */ 


EM_GETSEL 
EM_SETSEL 
EM_GETRECT 
EM_SETRECT 
EM_SETRECTNP 
EM_SCROLL 
EM_LINESCROLL 
EM_GETMODIFY 
EN_SETMODIFY 


EM_GETLINECOUNT 


EM_LINEINDEX 
EM_SETHANDLE 
EM_GETHANDLE 
EM_GETTHUMB 
EM_LINELENGTH 
EM_REPLACESEL 
EM_SETFONT 
EM_GETLINE 
EM_LIMITTEXT 
EM_CANUNDO 
EM_UNDO 
EM_FMTLINES 


EM_LINEFROMCHAR 
EM_SETWORDBREAK 
EM_SETTABSTOPS | 
EM_SETPASSWORDCHAR 
EM_EMPTYUNOOBUFFER 


WIN31 
EM_GETFIRSTVISIBLE 
EM_SETREADONLY 

/* WIN31 */ 
EM_MSGMAX 


/*® NOWINMESSAGES */ 


/* Button Control Styles */ 


(WH_USER+0) 
CWM_USER+1) 
(WM_USER+2) 
(WH_USER*3) 
CWH_USER+4) 
(WM_USER+S) 
(WM_USER*6) 
(WM_USER*8) 
(WH_USER+9) 
(WM_USER+10) 
CwM_USER*11) 
(WM_USER+12) 
(WM_USER*13) 
(WM_USER*14) 
(WM_USER*17) 
(WM_USER+18) 
(WM_USER*19) 
(WM_USER*20) 
CWM_USER#21) 
(WM_USER+22) 
(WM_USER+23) 
(WM_USER+#24) 
CWM_USER+25) 
(WM_USER#26) 
(WM_USER+#27) 
(WM_USER+28) 
(WH_USER#29) 


(WM_USER+30) 
(WM_USER+31) 


CWM_USER+32) 
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WINDOWS API BIBLE: 


AeA arate adr RE 2 IR ANP A 8 SR A PARA AE Be AE CE CE PENA A FN A I 


#define BS_PUSHBUTTON OxO0L 
#define BS_DEFPUSHBUTTON OxOiL 
#define BS_CHECKBOX Ox02L 
#define BS_AUTOCHECKBOX 0x03L 
#define BS_RADIOBUTTON Ox04L 
4#define BS_3STATE Ox05L 
H#define BS_AUTO3STATE - OxO6L . 
#define BS_GROUPBOX 0x07L 
#define BS_USERBUTTON 0x08L 
#define BS_AUTORADIOBUTTON Ox09L 
#define BS_OWNERDRAW OxOBL 
Adefine BS_LEFTTEXT Ox20L 


/* User Button Notification Codes */ 


define BN_CLICKED 0 

#define BN_PAINT 1 

#define BN_HILITE 2 

ddefine BN_UNHILITE 3 

#define BN_DISABLE 4 

4#define BN_DOUBLECLICKED 5 

/* Button Control Messages */ |. 

#define BM_GETCHECK CWM_USER+0) 
H#define BM_SETCHECK CWM_USER+1) 
#define BM_GETSTATE CWM_USER+2) 
4#define BM_SETSTATE (WM_USER+3) 
4define BM_SETSTYLE CWM_USER+4) 
/* Static Control Constants */ 

Hdefine SS_LEFT Ox00L 
#define SS_CENTER OxO01L 
#define SS_RIGHT 0x02L 
H#define SS_ICON Ox03L 
#define SS_BLACKRECT OxO04L = 
#define SS_GRAYRECT OxO5L 
Adefine SS_WHITERECT Ox06L 
Hdefine SS_BLACKFRAME Ox07L 
#define SS_GRAYFRAME : 0x08L 
#define SS_WHITEFRAME OxO09L 
d#define $S_USERITEM OxOAL 
Hdefine SS_SIMPLE | OxOBL 
#define SS_LEFTNOWORDWRAP OxOCL 
H#define SS_NOPREFIX Ox80L /* Don't do "&" character translation */ 
Hifdef WIN31 

Hifndef NOWINMESSAGES 

/* Static Control Mesages */ 

#define STM_SETICON (WM_USER+0) 
#define STM_GETICON CWM_USER+1) 
define STM_MSGMAX CWM_USER+2) 


Hendif /* NOWINMESSAGES */ 
Hendif /* WIN31 */ 


/* Dialog Manager Routines */ 

#Hifndef NOMSG 

BOOL API IsDialogMessageCHWND, LPMSG); 
#endif 

void API MapDialogRect(HWND, LPRECT); 


int API DigDirListCHWND, LPSTR, int, int, WORD); i et 


BOOL API DlgDirSelectCHWND, LPSTR, int); 
int API DigDirListComboBoxCHWND, LPSTR, int, int, WORD); 


BOOL API DlgDirSelectComboBox(HWND, LPSTR, int); 


/* DigDirList, DigDirListComboBox flags values */ 
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#define DDL_READWRITE 0x0001 
Hdefine DDL_READONLY 0x0002 
A#define DDL_HIDDEN 0x0004 
#define DDL_SYSTEM 0x0008 
Hdefine DDL_DIRECTORY. _ Qx0010 
H#define DDL_ARCHIVE ' 0x0020 
#define DDL_POSTMSGS 0x2000 
#define DDL_DRIVES™ - 0x4000 
#define DDL_EXCLUSIVE . 0xso00o0 


/* Dialog Styles */ 


H#define DS_ABSALIGN Ox01L 
#define DS_SYSMODAL Ox02e 
H#define DS_LOCALEDIT Ox20L /* Edit items get Local storage */ 
H#define DS _SETFONT Ox40L /* User specified font for Dig controls */ 
H#define DS_MODALFRAME Ox80L /* Can be combined with WS_CAPTION */ 
H#define DS_NOIDLEMSG Ox100L /* WM_ENTERIDLE message will not be sent */ 
H#define DM_GETDEFID CWM_USER+0) 
#define DM_SETDEFID CWM_USER+1) 
H#define DC_HASDEFID. oe 0x534B 
/* Dialog Codes */ 
4define DLGC_WANTARROWS 0x0001 /* Control wants arrow keys */ 
#define DLGC_WANTTAB 2 0x0002 /* Control wants tab keys */ 
#define DLGC_WANTALLKEYS ’ 0x0004 /* Control wants all keys */ 
H#define DLGC_WANTMESSAGE 0x0004 /* Pass message to control */ 
H#define DLGC_HASSETSEL 0x0008 /* Understands EM_SETSEL message */ 
#define DLGC_DEFPUSHBUTTON 0x0010 /* Default pushbutton */ 
H#define DLGC_UNDEFPUSHBUTTON 0x0020 /7* Non-default pushbutton */ 
H#define DLGC_RADIOBUTTON 0x0040 /* Radio button */ 
H#define DLGC_WANTCHARS 0x0080 /* Want WM_CHAR messages */ 
H#define DLGC_STATIC 0x0100 /* Static item: don't include */ 
#define DLGC_BUTTON 0x2000 /* Button item: can be checked */ 
#define LB_CTLCODE OL 
f 
/* Listbox Return Values */ 
#define LB_OKAY 0 
H#define LB_ERR (-1) 
#define LB_ERRSPACE (=-2) 
/* 


** The idStaticPath parameter to DlgDirList can have the following values 
** ORed if the List box should show other details of the files along with 
** the name of the files; : 

x/ 

/* all other details also will be returned */ 


/* Listbox Notification Codes */ 

#define LBN_ERRSPACE (-2) / 
#define LBN_SELCHANGE 1 

#define LBN_DBLCLK 2 

#define LBN_SELCANCEL 3 

#define LBN_SETFOCUS 4 

#define LBN_KILLFOCUS 5 


Hifndef NOWINMESSAGES 


/* Listbox messages */ 


H#define LB_ADDSTRING CWM_USER+1) 
#define LBLINSERTSTRING | CWM_USER+2) 
#define LB_DELETESTRING (WM_USER+3) 
H#define LB_RESETCONTENT C(WM_USER+5) 
#define LB_SETSEL CWM_USER+6) 
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#define 
Hdefine 
#define 
#define 
#define 
Rdefine 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
Hdefine 
#define 
#define 
#define 


Hdefine 


‘Hdefine 
#define 
| Adefine 


WINDOWS API BIBLE 


LB_SETCURSEL 
LB_GETSEL 
LB_GETCURSEL 
LB_GETTEXT 
LB_GETTEXTLEN 
LB_GETCOUNT- 


LB_SELECTSTRING 


LB_DIR 
LB_GETTOPINDEX 
LB_FINDSTRING 

LB_GETSELCOUNT 
LB_GETSELITEMS 


LB_SETTABSTOPS 


CWM_USER+7) 

CWM_USER+8) 

CWM_USER+9) 

CWM_USER+10) 
(WM_USER+11) 
CWM_USER+12) 
CWM_USER+13) 
CWM_USER+14) 
CWM_USER+15) 
CWM_USER+16) 
CWM_USER+17) 
CWM_USER+18) 
C(WM_USER+19) 


LB_GETHORIZONTALEXTENT 
LB_SETHORIZONTALEXTENT 
LB_SETCOLUMNWIDTH 


(WM_USER+20) 
(WM_USER+21) 
(WM_USER+22) 


LB_SETTOPINDEX 
LB_GETITEMRECT 
LB_GETITEMDATA 
LB_SETITEMDATA 
LB_SELITEMRANGE 


(WM_USER+24). 
(WM_USER+25) 
(WM_USER+26) 
(WM_USER+27) - 


- CWM_USER+28) 


‘Hdefine LB_SETCARETINDEX (WM_USER+31) 
Hdefine LB_GETCARETINDEX (WM_USER+32) 
a 
Hifdef WIN31 * 
#def ine LB_SETITEMHEIGHT (WM_USER+33) 
#define LB_GETITEMHEIGHT (WM_USER+34) 
Hendif /* WIN31 */ 
#define LB_MSGMAX © (WM_USER+35) 
Hendif /* NOWINMESSAGES */ 7 
Hifndef NOWINSTYLES: — - 
/* Listbox Styles */ 
. Adefine LBS_NOTIFY O0x0001L 
#define LBS_SORT Ox0002L 
define LBS_NOREDRAW 0x0004L 
#define LBS_MULTIPLESEL 0x0008L 
#define LBS_OWNERDRAWFIXED 0x0010L 
“ Adefine LBS_OWNERDRAWVARIABLE Ox0020L_. - 
H#define LBS_HASSTRINGS Ox0040L ~ 
define LBS_USETABSTOPS 0x0080L 
#define LBS_NOINTEGRALHEIGHT 0x0100L 
#define LBS_MULTICOLUMN 0x0200L 
Hdefine LBS_WANTKEYBOARDINPUT  0x0400L 
#define LBS_EXTENDEDSEL 0x0800L 
Hifdef WIN31 
H#define LBS_DISABLENOSCROLL 0x1000L 
Hendif /* WIN31 */ : i oe a wy 
#define LBS_STANDARD. (LBS_NOTIFY | LBS_SORT [| WS_VSCROLL | WS. BDRDER) 
Hendif /* NOWINSTYLES */ 


/* Combo Box return Values */ 


#define CB_OKAY 
#define CB_ERR 


#define 


CB_-ERRSPACE 


/* Combo Box Notification Codes */ 


#define 
#define 
H#define 
#define 
#define 
#define 
#define 


CBN_ERRSPACE 
CBN_SELCHANGE 
CBN_DBLCLK 
CBN_SETFOCUS 
CBN_KILLFOCUS 
CBN_EDITCHANGE 
CBN_EDITUPDATE 


(-1) 


aU eWN Oo 
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#define 
#ifdef 
#define 
Hendif 


CBN_DROPDOWN 7 
WIN31 

CBN_CLOSEUP 8 
/* WINST */ 


/* Combo Box styles */ 


#ifndef 
Hdefine 
#define 
#define 
#define 
#define 
H#define 
H#define 
Kdefine 
#define 
H#define 
Hifdef 

#define 
Hendif 

Hendif 


NOWINSTYLES 
CBS_SIMPLE 
CBS_DROPDOWN 
CBS_DROPDOWNLIST 
CBS_OWNERDRAWFIXED 
CBS_OWNERDRAWVARIABLE 
CBS_AUTOHSCROLL 
CBS_OEMCONVERT 
CBS_SORT . 
CBS_HASSTRINGS 
CBS_NOINTEGRALHEIGHT 
WIN31 
CBS_DISABLENOSCROLL ° 
‘7* WIN31 */ j 
/* NOWINSTYLES */ 


/* Combo Box messages */ 


*#ifndef 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
‘#define 
#define 
#define 
#define 
Hdefine 
#define 
#define 
#define 
H#define 
#define 
#define 
Hifdef 

#define 
Hdefine 
H#define 
#define 
#define 
#define 
#Hendi f 

#define 
Hendif 


#ifndef 


NOWINMESSAGES 
CB_GETEDITSEL 
CB_LIMITTEXT 
CB_SETEDITSEL 
CB_ADDSTRING 
CB_DELETESTRING 
CB_DIR 

CB_GETCOUNT 
CB_GETCURSEL 
CB_GETLBTEXT 
CB_GETLBTEXTLEN 
CB_INSERTSTRING 
CB_RESETCONTENT 
CB_FINDSTRING 
CB_SELECTSTRING 
CB_SETCURSEL 
CB_SHOWDROPDOWN 
CB_GETITEMDATA 
CB_SETITEMDATA 
WIN31 
CB_GETDROPPEDCONTROLRECT 
CB_SETITEMHEIGHT 
CB_GETITEMHEIGHT 
CB_SETEXTENDEDUI 
CB_GETEXTENDEDUI 
CB_GETDROPPEDSTATE 
/* WIN31 */ 
CB_MSGMAX 

/* NOWINMESSAGES */ 


NOWINSTYLES 


/* Scroll Bar Styles */ 


H#define 
#define 
‘Hdefine 
H#define 
H#define 
#define 
Hdefine 
H#define 
#define 


SBS_HORZ 
SBS_VERT 

SBS_TOPALIGN 

SBS_LEFTALIGN 
SBS_BOTTOMALIGN 
SBS_RIGHTALIGN 
SBS_SIZEBOXTOPLEFTALIGN 
SBS_SIZEBOXBOTTOMRIGHTALIGN 
SBS_SIZEBOX 


Hendif /* NOWINSTYLES */ 


0x0001L 
0x0002L 
0x0003L 
0x0010L 
0x0020L 
0x0040L 
Ox0080L 
0x0100L 
Ox0200L 
0x0400L 


0x0800L 


(WMUSER+0) 


(WM-USER+1) 
(WM_USER+2) 
(WM_USER+3) 
(WM_USER+4) 
(WM_USER+5) 
(WM_USER+6) 
(WM_USER+7) 
(WM_USER+8) 
(WM_USER+9) 
(WM_USER+10) 
(WM_USER+11) 
(WM_USER+12) 
(WM_USER+13) 
(WM_USER+14) 
(WM_USER+15) 
CWM_USER+16) 
(WM_USER+17) 


(WM_USER+18) 
(WM_USER+19) 
(WM_USER+20) 
(WM_USER+21) 
(WM_USER+22) 
(WM_USER+23) 


CWM_USER+24) 


Ox0000L 
0x0001L 
Ox0002L 


. Ox0002L 


Ox0004L 
Ox0004L 
0x0002L 
0x0004L 
0x0008L 
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WINDOWS API BIBLE ; 


Hendif /* NOCTLMGR */ 


#ifndef NOSOUND. 


int API OpenSound(void); 

void API CloseSound(void); : 

int API SetVoiceQueueSizeCint, int); 

int API SetVoiceNoteCint, int, int, int); 
int API SetVoiceAccent(int, int, int, int, int); 
int API SetVoiceEnvelope(int, int, int); 
int API SetSoundNoiseCint, int); 

int. API SetVoiceSound(int, LONG, int); 
int API StartSound(void); 

int API StopSound(void); 

int API WaitSoundState(Cint); 

int API SyncAllVoices(void); 

int API CountVoiceNotes(int); | 

LPINT API GetThresholdEvent (void); 

int API GetThresholdStatus(void); 

int API SetVoiceThreshold(int, int); 


/* WaitSoundState() Constants */ 
#define S_QUEUEEMPTY 0 
#define S_THRESHOLD 1 
#define S_ALLTHRESHOLD 2 


/* Accent Modes */ 


H#define S_NORMAL 0 
H#define S_LEGATO 1 
H#define S_STACCATO 2 


/* SetSoundNoise() Sources */ 


Hdefine S_PERIOD512 0 /* Freq = N/512 high pitch, less coarse hiss */ 
H#define S_PERIOD1024 1 /* Freq = N/1024 . */ 
#define S_PERI0D2048 2 /* Freq = N/2048 low pitch, more coarse hiss */ 
#define S_PERIODVOICE 3 /* Source is frequency from voice channel (3) ef 
#define S_WHITE512 4 /* Freq = N/512 high pitch, less coarse hiss */ 
H#define S_WHITE1024 5 /* Freq = N/1024 */ 
H#define S_WHITE2048 .. 6 /* Freq = N/2048 Low pitch, more coarse hiss */ 
#define S_WHITEVOICE 7 /* Source is frequency from voice channel (3) */ 
#define S_SERDVNA (-1)— /* Device not available */ 

H#define S_SEROFM (-2) /* Out of memory */ 

#define S_SERMACT . ~ (3) /* Music active */ 

Hdefine S_SERQFUL (-4) /* Queue full */ 

H#define S_SERBDNT (-5) /* Invalid note */ 

H#define S_SERDLN (-6) /* Invalid note length */ 

#define S_SERDCC (-7) /* Invalid note count */ 

define S_SERDTP (~8) /* Invalid tempo x, 

define S_SERDVL (-9) /* Invalid volume */ 

#define S_SERDMD (-10) /* Invalid mode */ 

H#define S_SERDSH (-11) /* Invalid shape xf] 

Hdefine S_SERDPT (-12) /* Invalid pitch © */ 

H#define S_SERDFQ (-13) /* Invalid frequency */ 

H#define S_SERDDR (-14)  /* Invalid duration wi 

#define S_SERDSR (-15) /* Invalid source */ 

#define S_SERDST (-16) /* Invalid state */ 


Hendif /* NOSOUND */ 


#ifdef USECOMM 


#define NOPARITY 0 
H#define ODDPARITY 1 
‘Hdefine EVENPARITY 2 
H#define MARKPARITY 3 
#define SPACEPARITY 4 
#define ONESTOPBIT 0 
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H#define ONESSTOPBITS 1 


H#define TWOSTOPBITS 2 

define IGNORE 0 /* Ignore signal */ 
H#define INFINITE OxFFFF /* Infinite timeout xf 
/* Error Flags */ 

#define CE_RXOVER. 0x0001 /* Receive Queue overflow — */ 
H#define CE_OVERRUN Ox0002 /* Receive Overrun Error */ 
H#define CE_RXPARITY 0x0004 /* Receive Parity Error : */ 
H#define CE_FRAME Ox0008 /* Receive Framing error */ 
#define CE_BREAK 0x0010 /* Break Detected */ 
#define CE_CTSTO 0x0020 /* CTS Timeout */ 
#define CE_DSRTO 0x0040 /* DSR Timeout */ 
#define CE_RLSDTO 0x0080 /* RLSD Timeout */ 
H#define CE_TXFULL 0x0100 /* TX Queue is full */ 
#define CE_PTO 0x0200 /* LPTx Timeout */ 
Hdefine CE_IOE 0x0400 /* LPTx 1/0 Error */ 
#define CE_ONS 0x0800 /* LPTx Device not selected *] 
H#define CE_OOP Ox1000 /* LPTx Out-Of-~Paper */ 
#define CE_MODE 0x8000 /* Requested mode unsupported */ 
#define IE_BADID (-1) /* Invalid or unsupported id ef 
#define IE_OPEN (-2) /* Device Already Open . */ 
#define IE_NOPEN . (-3) /* Device Not Open ' af. 
#define IE_MEMORY » (+4) /* Unable to allocate queues */ 
H#define IE_DEFAULT - (-5) /* Error in default parameters */ 
Hdefine IE_HARDWARE (-10) /* Hardware Not Present */ 
H#define IE_BYTESIZE (-11) /* Illegal Byte Size */ 
#define IE_BAUDRATE (-12) /* Unsupported BaudRate x/ 
/* Events */ 

#define EV_RXCHAR 0x0001 /* Any Character received . */ 
H#define EV_RXFLAG 0x0002 /* Received certain character */ 
#define EV_TXEMPTY 0x0004 /* Transmitt Queue Empty */ 
H#define EV_CTS 0x0008 /* CTS changed state - */ 
#define EV_DSR 0x0010 /* DSR changed state */ 
4#define EV_RLSD 0x0020 /* RLSD changed state */ 
#define EV_BREAK 0x0040 /* BREAK received */ 
#define EV_ERR 0x0080 /* Line status error occurred */ 
H#define EV_RING 0x0100 /*. Ring signal detected © */- 
H#define EV_PERR Ox0200 /* Printer error occured */ 
H#define EV_CTSS 0x0400 /* CTS state *x/ 
H#define EV_DSRS ; 0x0800 /* DSR state : */ 
#define EV_RLSDS 0x1000 /* RLSD state */ 
#define EV_RingTe - 0x2000 /* Ring trailing edge indicator */ 
4#define EV_RINGTE. EV_RingTe ; ; 


/* Escape Functions */ 


#define SETXOFF 1 /* Simulate XCFF received */ 
#define SETXON 2 /* Simulate XON received */ 
H#define SETRTS 3 /* Set RTS high */ 
Adefine CLRRTS 4 /* Set RTS low */ 
#define SETDTR 5 /* Set DTR high */ 
4#define CLROTR | 6 /*-Set DTR low */ 
#define RESETDEV 7 /* Reset device if possible */ 
H#define LPTx ' 0x80 /* Set if 1D is for LPT device */ 
#ifdef WIN31 

/* new escape functions 

H#define GETMAXLPT 8 /* Max supported LPT id */ 
#define GETMAXCOM 9 /* Max supported COM id a] 


H#define GETBASEIRQ 10 /* Get port base & irq for a port */ 


/* Comm Baud Rate indices */ 
#define CBR_110 OxFFI0 
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#define 
#define 
#define 
#define 
Hdefine 
#define 
#define 
#define 


cBR_300 
CBR_600 
CBR_1200 
cBR_2400 
CBR_4800 
CBR_9600 
CBR_14400 
CBR_19200 


/* #define CBR_RESERVED 


#define 
#define 


CBR_RESERVED 
CBR_38400 


/* #define CBR_RESERVED 


#define 
#define 
H#define 


CBR_RESERVED 
CBR_RESERVED - 
CBR_56000 


/* #define CBR_RESERVED 


#define 
#define 
#define 


CBR_RESERVED 
CBR_RESERVED 
CBR_128000 


/* #define CBR_RESERVED 


Hdefine 
Hdefine 
#define 


CBR_RESERVED 
CBR_RESERVED 
CBR_256000 


/* notifications passed 


#define 
H#define 


CN_RECEIVE 
CN_TRANSMIT 


Hendif /* WIN31 */ 


typedef 
{ i 
BYTE 
WORD 
BYTE 
BYTE 
BYTE 
WORD 
WORD 
WORD 


BYTE 
BYTE 
BYTE 
' BYTE 
BYTE 
BYTE 
BYTE 


BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 
BYTE 


char 
char 
WORD 
WORD 
char 
char 
char 
WORD 
} DCB; 


struct tagDCB 


Id; 
BaudRate; 
ByteSize; 
Parity; . 
StopBits; 
RlsTimeout; 
CtsTimeout; 
DsrTimeout ; 


fBinary: 1; 
fRtsDisable:1; 
fParity: 1; 
fOutxCtsFlow:1; 
fOutxDsrFlow:1; 
fDummy: 2; 
fDtrDisable:1; 


fOutX: 1; 
fInxX: 1; 
fPeChar: 1; y 
fNull: 1; 
fChEvt: 1; 
fDtrflow: 1; 
fRtsflow: 1; 
fDummy2: 1; 


XonChar; 
Xof fChar; 
XonLim; 

Xof flim; 
PeChar; 

EofChar; 
EvtChar; 
TxDelay; 


OxFF11 
OxFF12 
OxFFI3 
OxFFI14 
OxFF15 : ra 
OxFF16 ‘ 
OxFF17 

OxFF18 

OxFF1I9 

OxFFIA */ 

OxFF1B 

OxFFIC 

OxFF1ID 

OxFFIE */ 


- OxFFIF / ae 


OxFF20 
OxFF21 
OxFF22 */ 
OxFF23 
OxFF24 


“OxFF25 


OxFF26 */ 
OxFF27 


in low word of lParam on WM_COMMNOTIFY messages */ 
0x01 /* bytes are available in the input queue */ 
0x02 /* fewer than wOutTrigger bytes still */ 
/* remain in the output queue waiting */ 
/* to be transmitted. | */ 

@ 


/* Internal Device ID */ 
/* Baudrate at which runing . *f 
/* Number of bits/byte, 4-8 */ 
/* 0-4=None,0dd,Even,Mark,Space */ 
/*0,1,2 = 1, 1.5, 2 */ 
/* Timeout for RLSD to be set */ 
/* Timeout for CTS to be set */ 
/* Timeout for DSR to be set */ 


/* Binary Mode (skip EOF check */ 
/*®* Don't assert RTS at init time */ 


/* Enable parity checking ; */ 
/* CTS handshaking on output */ 
/* DSR handshaking on output */ 
/* Reserved */ 


/* Don't assert DTR at init time */ 


/* Enable output X~ON/X-OFF */ 
_/* Enable input X-ON/X-OFF */ 
/* Enable Parity Err Replacement */ 
/* Enable Null stripping */ 
/* Enable Rx character event. */ 
/* DTR handshake on. input */ 
/* RTS handshake on input */ 
/* Tx and Rx X-ON character x] 
/* Tx and Rx X-OFF character */ 
/* Transmit X-ON threshold */ 
/* Transmit X-OFF threshold x] 
/* Parity error replacement char */ 
/* End of Input character */ 
/* Recieved Event character */ 


/* Amount of time between chars */ 
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typedef 


typedef 
{ 


BYTE fCtsHold: 1 
BYTE fDsrHold:~1 
BYTE fRlsdHold: 


BYTE fXoffSent: 


DCB FAR * LPDCB; 

struct tagCOMSTAT 

/* Transmit is on CTS hold 

/*® Transmit is on DSR hold 

/* Transmit is on RLSD hotd 


/* Issued handshake 


, 
, 
1; 
BYTE fXoffHold: 1; /* Received handshake 
1; 


BYTE fEof: 1; /* End of file character found 
BYTE fTxim: 1; /* Character being transmitted 


- WORD cbInQue; /* count of characters in Rx Queue 
WORD cbOutQue; /* count of characters in Tx Queue 


} COMSTAT; 


int 
Hifdef 
BOOL 
Hendif 
int 
int 
int 
int 
int 
int 
int 
int 
int 
WORD 
WORD 
int 
int 
int 
LONG 


#endif 


#ifdef 

#ifndef 
#define 
#define 
H#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
H#define 
#define 


API OpenComm(LPSTR, WORD, WORD); 
WIN34 


API EnableCommNotification(Cint, HWND, int, int); 


/* WIN31 */ 
API SetCommState(LPDCB); 

API GetCommStateCint, LPDCB); 

API ReadCommCint, LPSTR, int); 

API UngetCommCharCint, char); 

API WriteCommCint, LPSTR, int); 

API CloseCommCint); 

API GetCommErrorCint, COMSTAT FAR *); 
API BuildCommDCBC(LPSTR, LPDCB); 

API TransmitCommCharCint, char); 

FAR * API SetCommEventMask(int, WORD); 


- API GetCommEventMask(int, int); 


API SetCommBreak(Cint); 

API ClearCommBreak(Cint); 

API FlushCommCint, int); 

API EscapeCommFunctionCint, int); 


/* USECOMM */ 


WIN31 

NODRIVERS 

DRV_LOAD ‘ 0x0001 
DRV_ENABLE 0x0002 
DRV_OPEN — 0x0003 
DRV_CLOSE 0x0004 
DRV_DISABLE 0x0005 
DRV_FREE 0x0006 


‘DRV_CONFIGURE 0x0007 


DRV_QUERYCONFIGURE 0x0008 
DRV_INSTALL 0x0009 


DRV_REMOVE 0x000A 


DRV_POWER Ox000F 
DRV_RESERVED 0x0800 
DRV_USER - 0x4000 


/* Supported return values for DRV_CONFIGURE message */ 


#define 
#define 
#define 


HANDLE 
LONG 
HANDLE 
LONG 
LONG 


HANDLE 


DRVCNF_CANCEL 0x0000 
DRVCNF_OK 0x0001 
DRVCNF_RESTART 0x0002 


API OpenDriver(LPSTR szDriverName, LPSTR szSectionName, LONG LParam2); 


API CloseDriver (HANDLE hDriver, LONG LParam1, LONG LParam2); 


API GetDriverModuleHandleCHANDLE hDriver); 


API SendDriverMessage(HANDLE hDriver, WORD message, LONG lParam1, LONG lParam2); 
API DefDriverProc(DWORD duDriverIdentifier, HANDLE driverIbD, WORD message, LONG 


lParam1, LONG LParam2); 
API GetNextDriverCHANDLE, DWORD); — 


/* GetNextDriver flags */ 
#define GND_FIRSTINSTANCEONLY 0x00000001 


#define 


GND_REVERSE 0x00000002 
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| typedef struct tagDRIVERINFOSTRUCT 


{ ; 
WORD Length; 
HANDLE hDriver; 
HANDLE hModule; 
char : szAliasNamel128]; 


} DRIVERINFOSTRUCT; es : 
typedef DRIVERINFOSTRUCT FAR *LPDRIVERINFOSTRUCT; 
BOOL API GetDriverInfoCHANDLE, LPDRIVERINFOSTRUCT); 


fendif /* !NODRIVERS */ 
Hendif /* WIN31 */ 


#ifndef NOMDI 
#Hifdef WIN31 
/* MDI client style bits */ 


#define MDIS_ALLCHILDSTYLES 0x0001 
/* wParam Flags for WM_MDITILE and WM_MDICASCADE messages. */ 
H#define MDITILE_VERTICAL 0x0000 
#define MDITILE_HORIZONTAL 0x0001 


H#define MDITILE SKIPDISABLED 0x0002 
Hendif /* WIN31 */ 


typedef struct tagMDICREATESTRUCT 


{ 
LPSTR szClass; 
LPSTR szTitle; 
HANDLE hOwner; 
int X,Y} 
int CX,CY; 
LONG style; 
LONG lParam; /* app-defined stuff */ 


} MDICREATESTRUCT; 
typedef MDICREATESTRUCT FAR * LPMDICREATESTRUCT; 


typedef struct tagCLIENTCREATESTRUCT 
{ 
HANDLE hWindowMenu; 
WORD idFirstChild; 
} CLIENTCREATESTRUCT; 


typedef CLIENTCREATESTRUCT FAR * LPCLIENTCREATESTRUCT; 


LONG APL Def FrameProc(HWND,HWND,WORD,WORD,LONG) ; 
LONG API DefMDIChildProcCHWND,WORD,WORD,LONG) ; 


H#ifndef NOMSG «._ 
BOOL API' TranslateMDISysAccel CHWND,LPMSG) ; 
Hendif re 


WORD API ArrangelconicWindows(HWND) ; 
#endif /* NOMDI */ 


Hifdet WIN31 
#ifndef NOSYSPARAMSINFO 
/* Parameter for SystemParametersiInfo() */ 


H#define SPI_GETBEEP 

H#detine SPI_SETBEEP 

’ A#define SPI_GETMOUSE 

H#define SPI_SETMOUSE 

Hdefine SPI_GETBORDER 
H#define SPI_SETBORDER 
H#define SPI_TIMEOUTS 

define SPI_GETKEYBOARDSPEED 


PB NAVUBWN = 
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4define SPI_LSETKEYBOARDSPEED 
#define SPI_LLANGDRIVER 

#define SPI_ICONHORIZONTALSPACING 
H#define SPI_GETSCREENSAVETIMEOUT 
H#define SPI_SETSCREENSAVETIMEOUT 
H#define SPI_GETSCREENSAVEACTIVE 
#define SPI_SETSCREENSAVEACTIVE 
#define SPI_GETGRIDGRANULARITY 
#define SPI_LSETGRIDGRANULARITY 
Hdefine SPI_SETDESKWALLPAPER 
Hdefine SPI_SETDESKPATTERN 
#define SPI_GETKEYBOARDDELAY 
H#define SPI_SETKEYBOARDDELAY 
Adefine SPI_ICONVERTICALSPACING 
Hdefine SPI_LGETICONTITLEWRAP 
#define SPI_SETICONTITLEWRAP 
#define SPI_GETMENUDROPALIGNMENT 
H#define SPI_SETMENUDROPALIGNMENT 
Adefine SPI_SETDOUBLECLKWIDTH. 
#define SPI_SETDOUBLECLKHEIGHT 
Hdefine SPI_GETICONTITLELOGFONT 
4#define SPI_SETDOUBLECLICKTIME 
ddefine SPI_SETMOUSEBUTTONSWAP 
Hdefine SPI_SETICONTITLELOGFONT 


APPENDICES v 


BOOL API SystemParametersInfo(WORD, WORD, LPVOID, WORD); 


/* Flags */ 

Hdefine SPIF_UPDATEINIFILE 0x0001 
#define SPIF_SENDWININICHANGE 0x0002 
H#define SPIF_VALID 0x0003 


Hendif /* NOSYSPARAMSINFO */ 
Hendif /* WIN31 */ 


Hendif /* NOUSER */ 
Hifndef NOHELP 
/* Help engine section. */ 


/* Commands to pass WinHelp() *, 


Hdefine HELP_CONTEXT 0x0001 
H#define HELP_QUIT ‘ 0x0002 
#define HELP_INDEX 0x0003 
H#define HELP_CONTENTS 0x0003 
#define HELP_HELPONHELP 0x0004 
#define HELP_SETINDEX 0x0005 
H#define HELP_SETCONTENTS 0x0005 
#define HELP_CONTEXTPOPUP 0x0008 
H#define HELP_FORCEFILE 0x0009 
#define HELP_KEY : 0x0101 
#define HELP_COMMAND 0x0102 
#define HELP_PARTIALKEY 0x0105 
#define HELP_MULTIKEY 0x0201 
#define HELP_SETWINPOS 0x0203 


BOOL API WinHelpCHWND hwndMain, LPSTR 


typedef struct tagMULTIKEYHELP 
{. 
WORD mkSize; 


BYTE. mkKeylist; 
BYTE szKeyphrase[1]; 


} MULTIKEYHELP; 


Hendif /* NOHELP */ 


/* Display topic in ulTopic */ 
/* Terminate help */ 
/*® Display index */ 


/* Display help on using help */ 
/* Set the current Index for multi index help */ 


/* Display topic for keyword in offabData */ 


/* call the search engine in winhelp */ 


LpszHelp, WORD usCommand, DWORD ulData); 
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#ifndef NOPROFILER 


/* function declarations for profiler routines contained in Windows 


int. API ProfInsChk(void); 

void API ProfSetup(Cint,int); 
void API ProfSampRateCint,int); 
void API ProfStart(vdid); 

void API ProfStop(void); 

void API ProfClear(void); 

void API ProfFlush(void); 

void API ProfFinish(€void); 


Hendif /* NOPROFILER */ 


#ifdef PRINTING 
typedef struct { 


short cbSize; 
LPSTR ; LpszDocName; 
LPSTR ‘LpszOutput; 
} DOCINFO, FAR * LPDOCINFO; 
int API StartDoc(HDC, LPDOCINFO); 
int API StartPage(HDC); : 
int API EndPageCHDC); 
int = API EndDoc(HDC); 
int API SetAbortProc(HDC,.FARPROC); 
int API AbortDoc(HDC); 
#endif 
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Libraries */ 


INDEX 


-#define, 857 
#elif, 857 
#endif, 857 
#if, 857 
#ifdef, 857 
#include, 856 
#undef, 857 
$ footnotes, 885 ~~ 
& character, 18, 109, 195, 558 
+ footnotes, 885 
-R switch, 855 
DEF, 5, 611, 617 
.DRV, 358 
.FON, 354 
8-bit sound resolution, 741 
16-bit sound resolution, 741 
32-bit coded keyboard data, 344 
32-bit keyboard data for WM_KEYUP, 
WM_KEYDOWN, 324 

80386 chip, 617 
80486 chip, 612, 617 
8086 chip, 612 
80x86 chip, 617 
_Lclose, 793-94 
_Lcreat, 794 
_LIseek, 795, 

position values, 795 
_LIseek, 795 | 
_Lopen, 795-96, 

access values, 796 
_Lread, 796 
_Lwrite, 796-97 


A 

Abort logic, 355 

Abort procedure, printing example, 
355-57 

Accelerator options, 197 

ACCELERATORS, 856 

AccessResource, 859-61 

AddAtom, 828-29 

AddFontResource, 360-61 

AdjustWindowRect, 35-36 

. AdjustWindowRectEx, 36-37 

Adlib Board, 741 

AllocResource, 861 

AND mask, 711 


AnimatePalette, 531-33 
ANSI character set, 758-59, 774 
AnsiLower, 760-61 
AnsiLowerBuff, 761-62 
AnsiNext, 762-63 
AnsiPrev, 763-64 
AnsiToOem, 764 
AnsiToOemBuff, 764-65 
AnsiUpper, 765 
AnsiUpperBuff, 765-66 
AnyPopup, 37 
AppendMenu, 111, 116-18 | 
flags, 117 
Arc, 441-42 
ArrangelIconicWindows, 712-14 
Atoms, 
and data exchange, 827 
atom tables, 826 
data structure, 826-27 
functions, 826-35 
local and global, 826 
Automatic (stack) variables, 615 
Automatic data segment, 611 


B 7 
BeginDeferWindowPos, 37-38 
BeginPaint, 442-43 
device handle context, using, 
435-36 
BiBitCount, 673° 
Bibliography, 937-38 
BiClrImportant, 672 
BiClrUsed, 672 
BiCompression, 672 
BiSizeImage, 672 
BitBlt, 676-78 
BITMAP, 
data type, 668 
resource script statement, 856 
Bitmap, 
adding graphics, 885-86 
checkmark, 112 
old format, 670-71 


stretching and painting images, 


670 
stretching modes, 692, 703 
structure, 668 . 


1003 


BITMAPFILEHEADER structure, 
\ 672 
BITMAPINFO structure, 672 
BITMAPINFOHEADER structure, 
672, 682 
Bitmaps, 668-709 
and memory device contexts, © 
669 
as menu items, 112 
DDB format, 668-69 
device-independent bitmaps 
(DIBs), 671-75 
functions, 675-709 
problems with old format, 
670-71 
BixPelsPerMeter, 672 
BiYPelsPerMeter, 672 
BmBits, 669 
BmBitsPixel, 668 
BmiColors, 672 
BmPlanes, 668-69 - 
BM_, 259 
BM_GETCHECK, 261 
BM_GETSTATE, 261 
BM_SETCHECK, 261 
BM_SETSTATE, 262 
BM_SETSTYLE, 262 . 
BN_, 259 é 
BN_CLICKED, 264 
BN_DISABLE, 264 
BN_DOUBLECLICKED, 264 
BN_HILITE, 265 
BN_PAINT, 265 
BN_UNHILITE, 265 
Bookmarks, adding, 885 
BOOL, 8, 33 
Boolean logic and bitmaps, 670 
BringWindowToTop, 39 
Brush, default, 437 
BuildCommDCB, 806-10 
BUTTON, 12-13, 19 
Button, 
controls, recognizing, 14 
messages, transmitted, 260-62 
notification codes, 262-65 
_ Styles, 20, 262 
BYTE, 8 


WINDOWS API BIBLE 


C 
C compiler library function and 
Windows, 355, 759, 760, 774, 

850, 892, 898 

_ CaliMsgFilter, 220-22 

CallWindowProc, 222-24 

CAPTION, 561 

Caret functions, 165-66 

CB_, 259 

CB_ADDSTRING, 270 

CB_DELETESTRING, 270 

CB_DIR, 270 

CB_FINDSTRING, 271 

CB_GETCOUNT, 271-72 | 

CB_GETCURSEL, 272 


CB_GETDROPPEDCONTROLRECT, 


272 
CB_GETEDITSEL, 272 
CB_GETEXTENDEDUI, 272-73 
CB_GETITEMDATA, 273 
CB  GETITEMHEIGHT, 273 
CB_GETLBTEXT, 273-74 
' CB_GETLBTEXTLEN, 274 
CB_INSERTSTRING, 274 
CB_LIMITTEXT, 274 
CB_RESETCONTENT, 275 
CB_SELECTSTRING, 275 


_ - CB_SETCURSEL, 275 


CB _SETEDITSEL, 276 
CB  SETEXTENDEDUI, 276 
CB_SETITEMDATA, 276 
CB_SETITEMHEIGHT, 277 
CB _SHOWDROPDOWN, 277 
CBN_, 259 
CBN_DBLCLK, 278 
CBN_DROPDOWN, 278 
CBN_EDITCHANGE, 278 
CBN_EDITUPDATE, 278-79. 
CBN_ERRSPACE, 279 “ 
CBN_KILLFOCUS, 279° 
CBN_SELCHANGE, 279 
CBN_SETFOCUS, 279 ~~ 
CContent library, 827 
ChangeClipboardChain, 
728-25 fe 

Character sets, — 

and fonts, 759 

and strings, 758-73 

conversions, 758 

functions, 760-73 
CHECKBOX, 562 


CheckDlgButton, 566-69 


- Checkmark bitmap, 112 


CheckMenultem, 111, 118-119 
flags, 119 
CheckRadioButton, 569 
Child windows, 13-17, 905 
ChildWindowFromPoint, 39-40 
Chord, 448-44 
CLASS, 561 
Class data, 29-30 
ClearCommBreak, 810-11 
Client area mouse button messages, 
164 
ClientToScreen, 166-67 
Clipboard, 719-40 
delayed rendering of data, 721-22 
formats, 720-21, 722, 728, 736-37 
functions, 723-40 
using, 719-20 
viewer programs, 722 
ClipCursor, 167-68 
Clipping region, 438 
CloseClipboard, 725 — 
CloseComm, 811 
CloseMetaFile, 839-41 
CloseSound, 744-45 
function, 742 
CloseWindow, 40-41 
CODE, 5, 616, 618 
CodeView for Windows, 17, 872, 874, 
898 
Color palette, 
control, 528-51 
functions, 530-51 
in Windows, 528-29 
messages, 530 
COLORREF, 438 
Color resolutions, 671, 692 
Colors, 438 
Color values, 438 
CombineRgn, 444-46, 
modes, 445 :. 
COMBOBOX, 19, 562 
Combo box, 
control, sending and receiving 
messages from, 266-67 
example, 268-69 © 
messages, 265-77 
notification codes, 277- 79 
owner-redrawn, 267-69 _ 
styles, 20-21 © 
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Communications, 

codes, 811-12 

error codes, 813 

event flags, 814, 817 

functions, 804-25 

support, 804-5 
Compiler memory models, 616-17 
Compiling and linking, 6-7 
Context stack, 437 
CONTROL, 562 
Controls, 17-18 
CopyMetaFile, 841 
CopyRect, 446 
CountClipboardFormats, 725 
CountVoiceNotes, 745-46 — 
CreateBitmap, 678-79 
CreateBitmapIndirect, 679-81 . 
CreateBrushIndirect, 447- 48 . 
CreateCaret, 168-70 
CreateCompatibleBitmap, 681-82 
CreateCursor, 170-72) 
CreateDC, 361-63 
CreateDialog, 569-73 
CreateDialogIndirect, 573-75 
CreateDialogIndirectParam, 575-77 
CreateDialogParam, 577-80 
CreateDIBitmap, 682-84 
CreateDIBPatternBrush, 684-86 
CreateDiscardableBitmap, 686-88 
CreateEllipticRgn, 449 


CreateEllipticRgnIndirect, 449- 50 


CreateFont, 363-65 
CreateFontIndirect, 365-66 
CreateHatchBrush, 450-51 
CreatelC, 366-67 
Createlcon, 714-16 
CreateMenu, 111,120 - 
CreateMetaFile, 841-42 — 
CreatePalette, 533-35 
CreatePatternBrush, 451-52 
CreatePen, 452-53 
CreatePenIndirect, 453-54 
CreatePolygonRgn, 454-55 
CreatePolyPolygonRgn, 455-56 
CreatePopupMenu, 111, 119-20 
CreateRectRgn, 456 
CreateRectRgnIndirect, 457 
CreateRoundRectRgn, 457-58 
CreateSolidBrush, 458-59 
CreateWindow, 4, 12-13, 18-24 . 
messages generated by, 17 


CreateWindowEx, 24-25 

CTEXT, 562 

CUA Advanced Interface Design 

Guide, 198 

CURSOR, 856 

Cursor 
boolean masks, 170 
functions, 169-70 
names, predefined, 180 


D 
Data attached to window or class, 
30 
Data queue, reading data in, 805. 
DATA, 5, 616, 618 
DBEditor, 552-53 
DC, also see device contexts, 
350-433 
DDB bitmaps, 
format, 668-69 
using, 669 
DDE, 
applications, 919 
cold link, 919-20 
cold link data transmission, 919 
conversation, initiation of, 919 
conversation, termination of, 920 
conversations, generalized, 922 
data exhange, 918 
data from Microsoft Excel, 927-28 
data transmission messages, 
other, 922-23 
hot link, 920 
item identifiers, 919 
messages, 929-35 
topics, 919 
warm link, 921 
DebugBreak, 875 
Debugging, 872-82 
Debugging functions, 874 
Default objects, 437-38 
Default palette, system, 520 
DefDlgProc, 580-84 
DeferWindowPos, 41-42 
flags, 42 ™ 
DefFrameProc, 915-16 
DefHookProc, 224-25 
DefMDIChildProc, 916-17 
DEFPUSHBUTTON, 562-63 
DefWindowProe, 226 


Delayed rendering of clipboard 
data, 721 
DeleteAtom, 829-30 — 
DeleteDC, 367-68 
DeleteMenu, 111, 121 
flags, 121 
DeleteMetaFile, 842 
DeleteObject, 459 
DESCRIPTION, 5, 618-19 
DestroyCaret, 172 
DestroyCursor, 172 
Destroylcon, 716 
DestroyMenu, 111, 121-22 
DestroyWindow, 42-43 
DeviceCapabilities, 368-71 
index values, 369 
Device contexts, 350-433 
and painting, 435-36 
mapping modes, 420 
private, 352 
saving, 352-54 
selecting objects into, 351-2, 
436-37 
DEVMODE, 358, 378 
DIALOG, 560 
Dialog box, 552-610 
communicating with dialog box 
controls, 556-58 
control statements, 561-65 
data structures, 559 
definition containing list box, 
557 
dynamic, 558-59 
function, 553-54 
functions, 565-610 
indirect and parameter dialog 
box functions, 556 
keyboard interface, 558 
modal, 555 
modeless, 555 
procedure for list box example, 
557-58 
styles, 21 
template statement description, 
560-61 
types. 555 
window messages, 280 
DialogBox, 584-87 
DialogBoxIndirect, 587-89 © 
DialogBoxIndirectParam, 589-92 
DialogBoxParam, 595-95 
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Dialog template statement descrip- 
tion, 560-61 
DIB bitmap, loading, 673-75 
DIBs, 671-75, 722 
DISCARDABLE, 616 
Disk files, 774-75 
DispatchMessage, 226-27 
Dithering, 438 
DigDirList, 777-79 
DigDirListComboBox, 780-81 
DigDirSelect, 782 . 
DigDirSelectComboBox, 782 
DLLs, 892-904 
about, 892 
and string functions, 760 
creating, 892-95 
debugging, 898 
function summary, 898-904 
importing Windows library func- 
tions, 897 
other ways to call functions, 896 
problems with writing, 897-98 
using functions in, 895-96 
DM_, 259 
DM_GETEFID, 280 
DM_SETEFID, 280 
DOS application in 386 mode, 217 
DOS file attributes, 777, 780, 794 
DPtoLP, 371-72 
DrawFocusRect, 459-60 
Drawlcon, 716-17 
DrawMenuBar, 111, 122-23 
DrawText, 372-74 
flags, 373 
DWORD, 8, 612, 918 
Dynamic data exchange (DDE), 
918-35 
Dynamic link libraries (DLL), 
892-904 


, 


E 

EDIT, 13, 19 

Edit control styles, 21 
EDITTEXT, 563 

EGA, 528 

Ellipse, 460 

EM_, 259 . 

EM_CANUNDO, 283 
EM_EMPTYUNDOBUFFER, 284 
EM_FMTLINES, 284 


. WINDOWS API BIBLE 


EM_GETHANDLE, 284 
EM_GETLINE, 285 
EM_GETLINECOUNT, 285 
EM_GETMODIFY, 285 
EM_GETRECT, 286-86 
EM_GETSEL, 286 
EM_GETTHUMB, 282 

- EM_LIMITTEXT, 286 
EM_LINEFROMCHAR, 286 . 
EM_LINEINDEX, 286-87 
EM_LINELENGTH, 287 
EM_LINESCROLL, 287 

~ EM "REPLACESEL, 287-88: 

__ EM_SETABSSTOPS, 289 
EM_SETFRONT, 282 
EM_SETHANDLE, 288 
EM_SETMODIFY, 288 
EM_SETPASSWORDCHAR, 288 

. EM_SETRECT, 288-89 
EM_SETRECTNP, 289 
EM_SETSEL, 289 

- EM_SETWORDBREAK, 290 
EM_UNDO, 290 
EmptyClipboard, 725-26 
EN_, 259 
EN_CHANGE, 291 

_ EN_ERRSPACE, 291 
EN_HSCROLL, 291 . 
EN_KILLFOCUS, 292 
EN_MAXTEXT, 292° 
EN_SETFOCUS, 292 — 

-EN_UPDATE, 292-93 - 
EN_VSCROLL, 293. ~ 
EnableHardwarelnput, 198- 99. 
EnableMenultem, 111, 128-25 
flags, 124 
EnableScrollBar, 149- 51 
EnableWindow, 43-44 
EndDeferWindowPos, 44 
EndDialog, 595 
EndPaint, 461 
EnumChildWindows, 44-45 


EnumClipboardFormats, 726-28 


Enumeration functions, 30-33 
EnumFonts, 374-76 
EnumMetaFile, 842-44 
EnumObjects, 462-64 
EnumProps, 47-48 
EnumTaskWindows, 49- BL 
EnumWindows, 51-53 


EqualRect, 464 
EqualRgn, 464-65 
Escape function version reference, 
380 

Escape, 379-81 

return codes, 380 
EscapeCommF unction, 811- 12 
ExcludeClipRect, 465-66 
ExcludeUpdateRgn, 466-67 


_ Execution profiling and debugging, 


872-82 


a functions, 874-82 


EXETYPE, 619 
ExitWindows, 227-28 . 
EXPORTS, 619 

' flags, 378 

Extended window styles, 24 
ExtFloodFill, 467-69 
ExtTextOut, 381-82 


F 


FAR, 10 

FatalExit, 875-76 

FErase, 435 

File attribute flags, anl, 297 

File names, obtaining from 
Microsoft Excel, 926-27 


- Files, 


initialization, 775- 16 

list of names, 775 
FillRect, 469 
FillRgn, 469-70 
FindAtom, 8380 
FindResource, 861-63 ~~ 
FindWindow, 53-54 ~ Se 
FIXED, 616 : 
FlashWindow, 54-55 
Flood fill types, 468 | 
FloodFill, 470-71 - 
FlushComm, 812 ~ 
FONT, 561, 856 
Font, default, 437 ~ 
Fonts, 354 


. Frame windows, a 


FrameRect, 471-72 
FrameRgn, 472-73 
FreeLibrary, 899-900 
FreeModule, 623-24 
FreeProcInstance, 228-30 
FreeResource, 863-64. 
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G A 
GDI function calls, 836-37 
GDI.EXE;7 
GENERIC, improving, 9-10. 
GENERIC.C, 

example program, 2-6 

header file, 4-5 
GENERIC.DEF 

definition file, 7 
module/definition file for 
GENERIC:C, 644 


i 


: GENERIC.DLG, 


dialog box definition file, 567 
dialog box template file, 
552-538 
GENERIC.H header file, 4 - 
GENERIC.HD dialog box item 
defines, 567 
GENERIC.ICO, 5 
GENERIC.INI file created, 786 
GENERIC.RC, 5, 109, 558 
GENERIC.RES, 855 
GENERIC2.C, changes to process 
WM_PAINT message, 9-10 
GENERICD.H dialog box ID Header 
file, 553 
GetActiveWindow, 29, 55 
GetAsyncKeyState, 200 - 
GetAtomHandle, 831 
GetAtomName, 831 
GetBitmapBits, 688-90 
GetBitmapDimension, 690-91 
GetBkColor, 382-83 | 


_ GetBkMode, 383-84 
‘GetBrushOrg, 473-74 


GetBValue, 474 
GetCapture, 172-73 
GetCaretBlinktime, 173-74 
GetCaretPos, 174-75 
GetCharWidth, 384-85 
GetClassInfo, 55-56 
GetClassLong, 56-58 

index values, 56 
GetClassName, 58-59 
GetClassWord, 59-60 

index values, 59 
GetClientRect, 60 
GetClipboardData, 728- 29 
GetClipboardFormatName, 729 
GetClipboardOwner, 729-30 


GetClipboardViewer, 730 
GetClipBox, 474-75 
GetClipCursor, 175-76 
GetCodeHandle, 624 
GetCodelnfo, 627 

data array, 627 
GetCommError, 812-13 
GetCommEventMask, 813-14 . 
-GetCommState#814-15 
GetCurrentPDB; 627-28 
- GetCurrentPosition, 475-76 
GetCurrentTask, 60-61 
GetCurrentTime, 850-51 
- GetCursorPos, 176-77 
GetDC, 385 
GetDCOrg, 386 
GetDesktopWindow, 61-62. 
GetDeviceCaps, 386-90 

index values, 389 
GetDialogBaseUnits, 595-96 
GetDIBits, 691-92 
GetDlgCtrlID, 596-97 
GetDlglItem, 597-98 
GetDlgItemInt, 598-99 
GetDlgItemText, 600 
GetDOSEnvironment, 782-83 
GetDoubleClickTime, 178-79 
GetDriveType, 783-84. 

returned values, 784 
GetEnvironment, 785 
GetFocus, 62-63 
GetFreeSpace, 628-29 
GetGValue, 474 
GetInputState, 201- y 
GetInstanceData, 864-66 
GetKBCodePage, 202 
GetKeyboardState, 202-3 
GetKeyboardType, 203-5 | 
GetKeyNameText, 205 
GetKeyState, 205-6 
GetLastActivePopup, 63-64 
GetMapMode, 390-91 
* GetMenu, 125 


GetMenuCheckmarkDimensions, 


125-27 ¢ 
GetMenultemCount, 127-28 
GetMenultemID, 128-29 
GetMenuState, 129-30 

return flags, 129 
wflags settings, 129 


GetMenuString, 130 

wilags settings, 180 
GetMessage, 217, 230-31 
GetMessagePos, 231-32 
GetMessageTime, 232-33 
GetMetaFile, 844-45 
GetMetaFileBits, 845-47 
GetModuleFileName, 629 
GetModuleHandle, 630 
GetModuleUsage, 630 
GetNearestColor, 476-77 
GetNearestPaletteIndex, 535-36 
GetNextDlgGrouplItem, 600-1 
GetNextDlgTabItem, 601-2 
GetNextWindow, 65 © 
GetNumTasks, 65-66 
GetObject, 477-78 
GetOpenClipboardWindow, 730-31 
GetPaletteEntries, 536-37 
GetParent, 66-67 
GetPixel, 479 
GetPolyFillMode, 479-80 
GetPriorityClipboardFormat, — 

732-34 

GetPrivateProfileInt, 785- a7 
GetPrivateProfileString, 787 
GetProcAddress, 900-1 
GetProfileInt, 787-89 
GetProfileString, 789 
GetProp, 67-69 - : 
GetRgnBox, 480-81 ° 
GetROP2, 481-83 
GetRValue, 474 
GetScrollPos, 151-53 
GetScrollRange, 153-55 
GetStockObject, 483-84 
GetStretchBltMode, 492-93 
GetSubMenu, 131-32 
GetSysColor, 485-86 . 
GetSysModalWindow, 69-70 . 
GetSystemDirectory, 789-90 
GetSystemMenu, 132-33 
GetSystemMetrics, 391-93 

nIndex values, 392 ae 
GetSystemPaletteEntries, 537- 38 
GetSystemPaletteUsd, 538-39 

flags, 539 


_ GetTabbedTextExtent, 393-94 


GetTempDrive, 790-91 
GetTempFileName, 791-92 _ 
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-GetTextAlign, 394-95 


flags, 394 
GetTextCharacterExtra, 396 
GetTextColor, 396-97 
GetTextExtent, 397-98 
GetTextFace, 398-99 
GetTextMetrics, 399-400 
GetThresholdEvent, 746-47 
GetThresholdStatus, 747-48 
GetTickCount, 851-52 
GetTopWindow, 70-71 
GetUpdateRect, 486-87 
GetUpdateRgn, 487-88 
GetVersion, 71-73 
GetViewportExt, 400-1 


‘GetViewportOrg, 402-3 


GetWindow, 72-73 
criteria, 72” 
GetWindowDC, 403-5 
GetWindowExt, 405 
GetWindowLong, 73-74 


GetWindowLong() index values, 73 


GetWindow0Org, 406 
GetWindowRect, 74-75 
GetWindowsDirectory, 792-93 
GetWindowYlask, 75-76 
GetWindowText, 77 
GetWindowTextLength, 77 
GetWindowWord, 77-78 
index values, 78 
GetWinF lags, 78-79 
flags, 79 
GhInstance, 10, 13 
Global descriptor table, 617 
Global heap, 612 
allocating memory in, 613-14 


_GlobalAddAton, 832-33 


GlobalAlloc, 630-33 

flags, 631 
GlobalCompact, 633-34 
GlobalDeleteAtom, 833 
GlobalDiscard, 636 
GlobalDosAlloc, 634-36 
GlobalDosFree, 636 
GlobalFindAtom, 833-34 
GlobalFix, 637-38 
GlobalF lags, 638-39 
flags, 638 | 
GlobalFree, 689 — 
GlobalGetAtomName, 835 
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GlobalHandle, 639 
GlobalLock, 639 . 
GlobalLRUNewest, 640-41 
GlobalLRUOldest, 641-42 
GlobalNotify, 642-45 
GlobalPageLock, 645-46 
GlobalPageUnlock, 646 
GlobalReAlloc, 646-47 

flags, 647 
GlobalSize, 647 
GlobalUnfix, 647-48 
GlobalUnlock, 648 © 
GlobalUnWire, 648-50 
GlobalWire, 650 
Graphics and music, 743 
GrayString, 406-7 
GROUPBOX, 563 . 


H 
HANDLE, 9 
Hardware palettes, 528 - ‘ 
Hatch brush patterns, 448, 451 
- HDC data type, 350, 435 
HDigModeless, 555 
HEAPSIZE, 5, 619-20 
Help document, 883° __ 
special characters, 884 
Help file, 883 
building, 883-84 
compiling, 886 - 
support, 883-91 - 
Help project file options, 
886-89 © 
_ Help system, using, 889 
_ HELPEX.HPJ help project file 
listing, 886 
HideCaret, 179 
HiliteMenultem, 133-35 
flags, 134 
HInstance, 10° 
HMF, 722 
Hot DDE conversation, sequence of, 
920 ; 
Hot keys, 558 
HPrevinstance, 10 
Hwnd, 13, 216 
Hypertext, 883 
defining jumps and index entries, 
885 
jump destinations, 884 


t 
IBM 8513/A, 528 
IBM 8514 and colors, 438 
IBM Music Feature Card, 741-  -__ 
IBM PC character set, 758 
ICON, 563, 856 
Icon files, 710 
IconResourceCount, 711 
Icons, 710-18 
creating at run time, 711 
functions, 712-18 
stock, 718 
using, 710-11 
IDM_DOIT, 3 
IDM_QUIT, 3 
Message, 11 
IMPORTS, 620 
InflateRect, 488-89: 
InitAtomTable, 835 
InSendmessage, 233-34 
InsertMenu, 111, 185-37 
data types, 136 - 
wF lags values, 136 
Instances and message loops, 10-11 
IntersectClipRect, 489-90 


- IntersectRect, 490-91 


Invalid rectangle, 435 
InvalidateRect, 491-92 


‘InvalidateRgn, 492-93 
‘InvertRect, 493-94. 


InvertRgn, 494-95 
IsCharAlpha, 766-67 
IsCharAlphaNumeric, 767 
IsCharLower, 767 
IsCharUpper, 767 ~ 
IsChild, 29, 80 
IsClipboardFormatAvailable, — 
734-85 
IsDialogMessage, 602-3 . 
IsDigButtonChecked, 603-4 
Islconic, 29, 80-82 
IsRectEmpty, 495-96 
IsWindow, 29, 82-83 
IsWindowEnabled, 83 
IsWindowVisible, 29, 84 
IsZoomed, 85. | 


K 
K footnotes, 885 - 


- KERNEL.EXE, 7 
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Keyboard accelerators, 195-98 
event types, 196 
recommended, 198 
resource file with, 196 
Keyboard messages, 193-95 
with non-English keyboards, 195 
wParam meaning in, 194 
Keyboard, 
code page values, 202 ~ 
functions, 198-214 
input message processing, 194-95 © 
support, 191-215 
type values, 204 
KillTimer, 852. 


L 

LB_, 259 | 
LB_ADDSTRING, 296 

LEZ DELETESTRING, 296 
LB_DIR, 296-97 
LB_FINDSTRING, 297 
LB_GETCARETINDEX, 297-98 | 
LB_GETCOUNT, 298 
LB_GETCURSEL, 298 
LB_GETHORIZONTALEXTENT, 298 
LB_GETITEMDATA, 298-99 
LB_GETITEMHEIGHT, 299 
LB_GETITEMRECT, 299 
LB_GETSEL, 299 
LB_GETSELCOUNT, 299-300 
LB_GETSELITEMS, 300 
LB_GETTEXT, 300 
LB_GETTEXTLEN, 300-01 
LB_GETTOPINDEX, 301 
LB_INSERTSTRING, 301 
LB_RESETCONTENT, 301 
LB_SELECTSTRING, 301-2 
LB_SELITEMRANGE, 302: 
LB_SETABSSTOPS, 304 
LB_SETCARETINDEX, 302 
LB_SETCOLUMNWIDTH, 302 
LB_SETCURSEL, 303 
LB_SETHORIZONTALEXTENT, 303 
LB_SETITEMDATA, 303 
LB_SETITEMHEIGHT, 303-4 


~ LB_SETTOPINDEX, 304° — 


LB_SETSEL, 804 
LBN_, 259 

LBN “DBLCLK, 305 
LBN_KILLFOCUS, 305 


a 


LBN_SELCHANGE, 305-6 
LBN_SETFOCUS, 306 
LIBRARY, 620 
LimitEmsPages, 650 
LineDDA, 496-97 
LineTo, 497-98 
LISTBOX, 19, 563-64 
List box, 
control, 294-95 
messages, 293-305 
notification codes, 305-6 
_ owner-redrawn; 295 - 
styles, 22 
LoadAccelerators, 206-9 
LoadBitmap, 693-95 
LoadCursor, 179-81 
LoadIcon, 717-18 
LoadLibrary, 901-2 
error codes, 901-2 / 
LoadMenu, 111, 137-38 
LoadMenulndirect, 1388-40 
LoadModule, 650-53 
error codes, 651 
LOADONCALL, 616 | 


‘ LoadResource, 866-67 


LoadString, 867-68 
Local descriptor table, 617 
Local heap, 611 

allocating memory in, 612-13 
LocalAlloc, 653-56 

flags, 654 
LocalCompact, 656-57 
LocalDiscard, 657 
LocalFlags, 658 

flags, 658 
LocalFree, 658-59 
LocalHandle, 659-60 
LocalInit, 902-4 
LocalLock, 660 
LocalReAlloc, 660-61 

flags, 660-61 
LocalShrink, 661-62 
LocalSize, 662 
LocalUnlock, 662-63 
LockResource, 869 
LockSegment; 663-64 
Logical brush, 

color types, 447 

types, 447 
Logical fonts, 354 
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Memory blocks, 


Logical palette, 529-30 

Logical units, 353 locked, fixed, and page-locked, 
LONG, 1 617 ; 
Long pointers, 612 moveable, fixed, and discardable, 
LParam, 11 , 614 ~ , 
LpCmdLineShowWindow styles, 666 | MENU, 564 


LpCmdShow ShowWindow styles, 652 Menu, 109-46 


LPSTR, 9, 612 adding to program’s window, 111 
LPtoDP, 408 building in the resource file, 
Lstreat 767-69 109-11 


_ Lstremp, 769-70 


Lstrcmpi, 770 
Lstrepy, 770 
Lstrlen, 771 
LTEXT, 564 


M ‘ 


Macros from WINDOWS.H, 939 ~ 


Main menus, 109 
MAKEPOINT, 498 
MakeProcinstance, 2385 
MapDialogRect, 604-5 
Mapping modes, 352-54 
device context, 420 
fixed size, 353 
that can be scaled, 353 


MapVirtualKey, 209-10 ae 


codes, 210 
MDI, 
application structure, 905-7 
example program, 907-15 
frame and child windows, 905 
functions, 915-17 
interface bugs, 907 
message summary, 906-7 
MDICLIENT, 19 . 
Memory, - 
allocating in the global heap, 
613-14 
allocating in the local heap, 
612-18 
blocks, 614, 617 
compiler memory models, | 
616-17 . 
configurations, 615-16 
functions, 621-669 
local and global, 611-12. 
management, 611-69 
problems,.615 _ 
segments and offsets, 612 
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changing, 111 
functions, 115-46 
item options, 110 
Thain, 109 
messages, 115 
popup, 109 
Menu items, 
bitmaps as, 112 
checked, 110 
graying, 110 
owner-drawn, 112-15 — 
MENUITEMTEMPLATE mtOption 
flags, 139 
Message box, 
flags, 606-7 
returned values, 606 
Message flow, 216-18 
Message hook functions, 218-19 
Message loop, 217 
Message processing, 14-17, 217 
functions, 216-57 
Message sources, 217-18 
MessageBeep, 748 
MessageBox, 606 
Messages, 


button notification codes, 262-65 


combo box, 265-67 
edit control, 280-90 
edit control notification, 290-93 
list box, 293-305 

sources of, 217 

static contrdl, 306-7 
transmitted, 259-260 
transmitted button, 260-62 


- Metafiles, 836-48 


altering metafile image, 838 

creating and displaying disk 
metafile, 836-37 - 

creating and playing memory 
metafile, 836 
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disk format, 837-38 
functions, 839-48 
limitations, 838-39 
METAHEADER structure, 837-38 
METARECORD structure, 838 
Microsoft Excel, 918, 926-28 
Microsoft Word for Windows, 883, 
918 
MIDI, 741 . 
Modal dialog box, 555 
Modeless dialog box, 555 
-ModifyMenu, 111, 141-42 
data types, 142 
flags, 142 . ict 
Modules, 
definition statements, 617-21 
running other, 617 
Monochrome icon bit masks, 714 
Mouse, 
flags, 340, 341 
functions, 165, 166-90 
hit test codes, 940 
key flags, 325, 326, 327, 332 
messages, 163-64 
Mouse and cursor functions, 163-90 
MOVEABLE, 7, 616 
MoveTo, 498-99 
MoveWindow, 29, 85- 86 
MS-DOS 
and disk file access, 774-803 
and disk file functions, 776-803, 758 
MulDiv, 664-65 
Multiline edit control, creating, 
* 281-82 . 
Multiple document interface 
(MDI), 905-7 — 


N 

» NAME, 620 | 

NCmdLine, 10 

NCmdShow, 11 

NMAKE, 5-7, 855 — 

Note queue, 742 

Notes, 30-88 

NOTIFY NMAKE file for 
NOTIFY.DLL, 644 

NOTIFY.C source code for 


notification function DLL, 643 


NOTIFY.DEF definition file 
for DLL, 643 


O 

OEM character set, 758-59, 774 
OemKeyScan, 210-212 
OemToAnsi, 771-72 
OemToAnsiBuff, 772 
OffsetClipRgn, 499-500 — 
OffsetRect, 500-1 
OffsetRgn, 501-2 

Offsets, 612 
OffsetViewportOrg, 408- 10 
OffsetWindowOrg, 410 


OFSTRUCT data structure, 774-75 


OpenClipboard, 735 
OpenComm, 815-16 
error codes, 815 

OpenFile, 797-99 
flag values, 798 


. Openicon, 718 


OpenSound, 748 

function, 742 
OutlineBlock function, 738- 40 
OutputDebugString, 876 


P 

Painting, 434-527 
functions, 439-527 

PaintRgn, 502-3 

PAINTSTRUCT data structure, 

301 

PALETTEENTRY flags, 533 

PALETTEINDEX, 539-41 

PALETTERGB, 541 

PASCAL statement, 10° 

PatBlt,695 

PC speaker, 741 

PeekMessage, 235-38, 805 
flags, 236 


_Pen and brush, selecting into 


device context, 436-37 
Pen, default, 437 


Pie, 503-4 


Pixels, 352 

Playing one voice, 742 

PlayMetaFile, 847 | 

PlayMetaFileRecord, 847-48 

POINT, 9 

Polygon filling modes, 454, a 
480, 517 

Polygon, 504 

Polyline, 504-5 
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PolyPolygon, 505-6 


Popup menus, 109 
PostAppMessage, 238-40 
PostMessage, 240-41 
PostQuitMessage, 241-42 
PRELOAD, 616 
Printer, 
device driver, 357- 58 
support, 354-57 
support, minimal, 354-55 
Printing, 350-433 
ProfClear, 876-78 
ProfFinish, 879 _ 
ProfFlush, 879 
Profiler, 
about, 872 
preparing to run, 872-74 
using, 874° 0° mS 
ProfInsChk, 879 
ProfSampRate, 879-80 
ProfSetup, 880-81 
ProfStart, 881 
ProfStop, 881 
Program code, moveable, 616 
Program control, 217 - oe 
Program group, adding to program 
manager, 923-26 
Programming, 1-11 
reference books, 937-38 


_ Project [alias] section, 888 
~ Project [bitmaps] section, 


888-89 ; 
Project [buildtags] section, - 
886-87 
Project [files] section, 886 
Project [map] section, 888 ; 
Project [options] section, 887-88 
PSTR, 9, 612 


' PtInRect, 506-7 


PtInRegion, 507-8 
PtVisible, 508-9 
PUSHBUTTON, 564 


R 
RADIOBUTTON, 564 
Raster drawing modes, 521 
Raster-operation codes, 482, 670, 
676-77, 704, 707 
that PatBlt can use, 695 
RCDATA, 856, 858 


INDEX ¥ 


RC.EXE, 5, 855 
RePaint, 351 
-RdFunction, 838 
ReadComm, 816 
RealizePalette, 541-42 
Receive data queue, 804 
RECT, 9 
Rectangle, 510 
RectInRegion, 510-11 
RectVisible, 511-12 
Reentrant functions, 17, 218 
Reference count, 617, 826 
Region types, 445, 465, 466, 475, 
_ 481, 487, 489, 499, 501, 514 
Regions, 438 
RegisterClass, 26-28 
window Styles, 26 
RegisterClipboardFormat, 736 
RegisterWindowMessage, 
242-44 
ReleaseCapture, 181-82 
ReleaseDC, 410-11 
RemoveFontResource, 411-12 
RemoveMenu, 142-43 
flags, 148 
RemoveProp, 86-87 
ReplyMessage, 244-45 
ResetDC, 412-15 
ResizePalette, 542-43 
Resource compiler switches, 
855-56 
Resource file with keyboard 
accelerators, 196 
Resource script file, 109 
with menu items grayed and 
checked, 110 
Resource types, predefined, 862 
Resource, 
compiler, 855-56 
file, 109-11 
script file, 856-57 
Resource.rc file, 117 
Resources, 855-71 
custom, 858 
functions, 859-71 
RestoreDC, 415-16 
RGB, 488, 512-138 
RGBQUAD, 672, 683 
RoundRect, 513-14 
RTEXT, 564-65 


S . 
Sampling rates for non-386 en- 
hanced mode profiling, 880 

SaveDC, 416 
ScaleViewportExt, 416-17 
ScaleWindowkxt, 418 
ScreenToClient, 182-83 
SCROLLBAR, 18, 19, 565 
Scroll bar, 147-62 

attachment to window border, 

148 

class, 18 

codes, 322, 348 

concepts, 147-48 

creating, 147 

functions, 149-62 

messages, 148-49 

position and range, 148 

styles, 22 

types, 150, 151, 158, 160 
ScrollIDC, 155-56 
ScrollWindow, 157-59 
SDK, 168, 552, 775, 872, 883 
SDKPaint, 6, 112, 165, 669, 673, 710 
Search strings, adding, 885 
SEGMENTS, 616, 621 
Segments and offsets, 612 
SelectClipRgn, 514-15 
SelectObject, 515 
SelectPalette, 543-44 
SendDlgItemMessage, 607-9 
SENDER.C, 244-45 
SendMessage, 246-47 
SetActiveWindow, 29, 87-88 
SetBitmapBits, 696-97 
SetBitmapDimension, 697 
SetBkColor, 418-19 
SetBkMode, 419 


~ SetBrushOrg, 515-16 


SetCapture, 183 
SetCaretBlinkTime, 184 
SetCaretPos, 184-85 
SetClassLong, 30, 88-89 
flags,88 
SetClassWord, 30, 89-91 
flags, 90 
SetClipboardData, 736-40 
SetClipboardViewer, 740 
SetCommBreak, 816-17 


SetCommEventMask, 817-20 
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SetCommState, 820-21 
SetCursor, 185-86 
SetCursorPos, 186-87 
SetDIBits, 697-700 
SetDIBitsToDevice, 700-2 
SetDigitemInt, 609-10 
SetDlgltemText, 610 
SetDoubleClickTime, 187-88 
SetEnvironment, 800 
SetErrorMode, 800-1 
SetFocus, 29, 91 
SetHandleCount, 801 
SetKeyboardState, 212-13 
SetMapMode, 419-20 
SetMapperFlags, 420-21 
SetMenu, 111,148 
SetMenultemBitmaps, 144 

flags, 144 
SetMessageQueue, 248 
SetMetaFileBits, 848 
SetPaletteEntries, 544-46 
SetParent, 91-92 
SetPixel, 516-17 
SetPolyFillMode, 517 
SetProp, 92-93 
SetRect, 518 
SetRectEmpty, 518-19 
SetRectRgn, 519-20 
SetResourceHandler, 869-71 
SetROP2, 520-22 
SetScrollPos, 159-60 = ~~ 
SetScrollRange, 160-61 
SetSoundNoise, 749 

values, 749 
SetStretchBltMode, 702-3 
SetSysColors, 522-24, 545-47 
SetSysModalWindow, 93-94 
SetSystemPalettleUse, 547-49 

‘lags, 54 
SetTextAlign, 421-22, 

flags, 422 
SetTextCharacterExtra, 422-23 
SetTextColor, 423-24 
SetTextJustification, 424-25 - 
SetTimer, 852-54 
SetViewportExt, 425-26 


SetViewportOrg, 426-27 


SetVoiceAccent, 750-51 
. error codes, 750 
mode values, 751 
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SetVoiceEnvelope, 751-52 
error codes, 751 
SetVoiceNote, 752-53 | 
error values, 753 
SetVoiceQueueSize, 153 
error codes, 753 
SetVoiceSound, 754 , 
error codes, 154 
SetVoiceThreshhold, 754-56 
SetWindowExt, 427-28 
SetWindowLong, 30, 94-96 
flags, 95 
SetWindowOrg, 428 
SetWindowPos, 96- 98 
flags, 97 
SetWindowsHook, 048- 55 
SetWindowText, 98 
SetWindowWord, 30, 99 
flags, 99 . 
ShowCaret, 188 
ShowCursor, 188-89 
ShowOwnedPopups, 100 
ShowScrollBar, 161-62 
ShowWindow, 4, 100-2 
flags, 10 - 
SizeofResource, 871 
Sound Blaster Card, 741 
Sound drivers, 741-42 
support and information, 938 
Sound function error codes, 743 
Sound, 
- functions, 741-57 
sources, 741. 
support, 741 _ 
synthesis chip, 741 
SOUND.DRYV, 741 
STACKSIZE, 5, 621. 
StartSound, 756 
STATIC, 13, 19 
Static class, 17 
Static control, 
- control styles, 23 
messages, 306-7 © 
Static data, 611 
STM_GETICON, 306 
STM_SETICON, 306-7 
Stock icons, 718 
Stock objects, 437-38 
Stopping sound playback, 742 
StopSound, 756 
StretchBit, 703-5 


StretchDIBits, 705-9 
String manipulation functions, 
759-73 


- String tables, 857-58 


STRINGTABLE, 856 


STUB, 621 . # <a 


STYLE, 560 

Super VGA and colors, 438, 528 
Support functions, 29-108 
SwapMouseButton, 189-90 
SyncAllVoices, 757 . 
SYSEDIT.EXE, 905 


. System colors, 485, 523 


System default palette, 529 
SYSTEM.INI, 741 
SystemParametersInfo, 102-6 
wAction values, 105 
“System” topic items, 922 


T 
TabbedTextOut, 429 


~ Task header, 611 


Text and device context functions, 
358-433 


- Text output, 350-433 


TextOut, 430 
Time functions, 850 - 
Timer, 805, 848-54 
accuracy, 849-50 
functions, 850-54 
using, 849 
ToAscii, 773 | 
TrackPopupMenu, 144-46 
TranslateAccelerator, 213-14 
TranslateMDISysAccel, 917 
TranslateMessage, 217, 255-56 
Transmit data queue, 804 
TransmitCommChar, 821-24 


U 

UngetCommChar, 824-25 

UnhookWindowsHook() hook types, 
256 


~ UnhookWindowsHook, 256 
UnionRect, 524 


UnlockSegment, 665 
UnrealizeObject, 525 
UnregisterClass, 106-7 


_ UpdateColors, 549-51 


UpdateWindow, 526 . 
USER.EXE, 7 
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ValidateCodeSegments, 881-82 
ValidateFreeSpaces, 882 
ValidateRect, 526-27 
ValidateRgn, 527 
VGA and colors, 438, 528, 668 
Viewport extent, 353 
Virtual key codes, 193 
Virtual keys, 191-93 
VkKeyScan, 214-15, 

codes, 214. 
Voice thresholds, 748 
Voices and voice queues, 742- 43 
WwW ate > 
WaitMessage, 257 
WaitSoundState, 757. 

values, 757 
Warm DDE conversation, sequence 
of, 921 


’ WH_CALLWNDPROC, 249-50 


WH_GETMESSAGE, 250 ee 
WH_JOURNALPLAYBACK, 250 
WH_JOURNALRECORD, 250-51 
WH_KEYBOARD, 251 
WH_MSGFILTER, 251 
nCode values, 251 
WH_SIZE, 11 
Windclass structure, 4 
WINDENUM.C WindProc() function 
and enumeration functions, 
52-53 . 
WINDENUM.C WndProc() function, 
31-33 
WINDENUM.DEF, 31 
WINDENUM.H header file for child 
window enumeration, 31 
WINDEXM2, 14 
WINDEXM2.C, 15-16 
WINDEXM2.DEF definition file, 
16-17 
WINDEXM2.H header file, 16 
Window 
attributes, changes to, 29 
classes, creating new, 14-17 
creation functions, 18-28 
extent, 503 
styles, 17-18, 23-24 
Window messages, 307-49 
dialog box, 280 
" summary, 308-11 


WindowFromPoint, 107-8 
Windows GDI, 4384 
Windows 
books about, 937 
creating, 12-28 
creating, using different base 
class, 12-13 © 
import library names, 897 
messages, 17, 259-307, 259 
support functions, 33-108 
time, 850 
Windows Multimedia Developer's 
Kit, 741 
Windows Program Manager, 
' creating new group inside, 
923-26 
_ DDE commands, 922-23 
Windows Software Development Kit, 
. 163, 552, 775, 872, 883 
Windows Spy program, 163 
WINDOWS.H, 
excerpt, 8-9 
header file, 7-9 
listing, 941-1002 
macros, 939 > 
WINDCLASS definition in, 29-30 
WinExec, 665-67, 
error codes, 665-66 
WINEXM2.H header file, 16 
WinHelp, 889-91, 
command, 889 
- WinMainQ), 1 
WinProc() function, 117-18 
WINSTUB, 5 
WM_, 259 
WM “ACTIVATE, 312 
WM_ACTIVATEAPP, 312 
WM_ASKCBFORMATNAME, 312 
WM_CANCELMODE, 312 
WM_CHANGECBCHAIN, 312, 722 
WM_CHAR, 194, 217, 3138 
lParam coding, 313 
WM_CHARTOITEM, 313 
WM_CHILDACTIVATE, 313 
WM_CLEAR, 283, 314 
WM_CLOSE, 314 
WM_COMMAND, 3, 14, 314 
-WM_COMPACTING, 314 
WM_COMPAREITEM, 314-15 
_ WM_COPY, 283, 315 7 
WM_CREATE, 17, 19, 315-16 © 


WM_CTLCOLOR, 316 
values, 316 
WM._CUT, 283, 316 
WM_DDE_ACK, 929-30, 
]Param low-order word flags for, 
930 
WM_DDE_ADVISE, 930- 31, 
]Param low-order word flags for, 
. 931 
WM_DDE_DATA, 931-82, 
1Param low-order word flags for, 
932 
WM_DDE_EXECUTE, 932-33 
WM_DDE_INITIATE, 933 
WM_DDE_POKE, 934 
WM_DDE_REQUEST, 934- 35 
WM_DDE_TERMINATE, 935 
WM_DDE_UNADVISE, 935 
WM _DEADCHAR, 195, 316-17 
IParam coding, 317 
WM_DELETEITEM, 317 
WM_DESTROY, 3, 4, 317-18 
WM_ DESTROYCLIPBOARD, 318, 
722 
WM_DEVMODECHANGE, 318 
WM_DRAWCLIPBOARD, 318 
WM_DRAWITEM, 117, 142, 318-19 
WM_DROPFILES, 319 
WM_ENABLE, 83, 319. 
WM_ENDSESSION, 319 
WM_ENTERIDLE, 319 
WM_ERASEBKGND, 319-20 
WM_FONTCHANGE, 320 
WM_GETDLGCODE, 320 
return flags, 320 
WM_GETFONT, 320-21 
WM_GETMINMAXINFO, 17, 321 
point array values, 321 
WM_GETTEXT, 321-22 
WM_GETTEXTLENGTH, 322 
WM_HSCROLL, 148, 322 
WM_HSCROLLCLIPBOARD, 322-23 


. WM_ICONERASEBKGND, 323 


WM_INITDIALOG, 323, 554, 576 
WM_INITMENU, 323. 
WM_INITMENUPOPUP, 115, 323 
WM_KEYDOWN, 194, 195, 324 
32-bit keyboard data for, 324 


| WMLKEYUP, 194, 195, 324. 


32-bit keyboard data for, 324 


WM_KILLFOCUS, 166, 324 
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 WM_LBUTTONDBLCLK, 


164 , 324-25 

WM _LBUTTONDOWN, 163, 164, 325 
WM_LBUTTONUP, 164, 305. 26 
WM_MBUTTONDBLCLK, 326 
WM_MBUTTONDOWN, 326 
WM_MBUTTONUP, 326-27 
WM_MDIACTIVATE, 327, 906 
WM_MDICASCADE, 327, 906 
WM_MDICREATE, 328, 906 
WM_MDESTROY, 328, 906 . 
WM_MDIGETACTIVE, 328 
WM_MDIICONARRANGE, 329, 906 
WM_MDIMAXIMIZE, 329, 906 
WM_MDINEXT, 329, 906 
WM_MDIRESTORE, 329, 907 
WM_MDISETMENJU, 330, 907 
WM_MDITILE, 330, 907 

flags, 330 
WM_MEASUREITEM, 117, 142, 

330-31 

WM_MENUCHAR, 115, 331 
WM_MENUSELECT, 331 

flags, 331 
WM_MOUSEACTIVATE, 332 

return codes, 332 
WM_MOUSEMOVE, 164, 332 
WM_MOVE, 85, 176, 333 
WM_NCACTIVATE, 333 
WM_NCCALCSIZE, 17, 333 
WM_NCCREATE, 17, 19, 333 
WM_NCDESTROY, 333 
WM_NCHITTEST, 163,334 
WM_NCLBUTTONDBLCLK, 334 
WM_NCLBUTTONDOWN, 164, 334 
WM_NCLBUTTONUP, 334> 
WM_NCMBUTTONCBLCLK, 334 
WM_NCMBUTTONDOWN, 835 
WM_NCMBUTTONUP, 335 


_WM_NCMOUSEMOVE, 163, 335 


WM_NCPAINT, 1238, 335 
WM_NCRBUTTONDBLCLK, 335 


- WM_NCRBUTTONDOWN, 336 


WM_NCRBUTTONUP, 336 
WM_NEXTDLGCTL, 336 
settings, 336 

WM_NULL, 336 

WM ~OTHERWINDOWCREATED, 
337 

WM_! OTHERWINDOWDESTROYED, 
oa 
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WM_PAINT, 9-10, 337,351, 434-35, 
typical logic, 434-35 
WM_PAINTCLIPBOARD, 337-38 
WM_PAINTICON, 338 
WM_PALETTECHANGED, 338 
WM_PARENTNOTIFY, 19, 338. 
codes, 338 
WM_PASTE, 283, 339 
WM_QUERYDRAGICON, 339 
WM_QUERYENDSESSION, 339 
WM_QUERYNEWPALETTE, 339 
WM_QUERYOPEN, 339-40 
WM_QUIT, 340 


-_ WM_RBUTTONDBLCLK, 164, 340 


WM_RBUTTONDOWN, 163, 164, 
340-41 | 
~ WM_RBUTTONUP, 164, 341 
WM_RENDERALLFORMATS, 
341, 722 
WM_RENDERFORMAT, 341 
WM_SETCURSOR, 163, 165, 341-42 
WM_SETFOCUS, 166, 342 
WM_SETFONT, 342 
WM_SETREDRAW, 342-43 
WM_SETTEXT, 343 
WM_SHOWWINDOW, 17, 343 
WM_SIZE, 85, 176, 343-44 
WM_SIZECLIPBOARD, 344 
WM_SPOOLERSTATUS, 344 ' 
WM_SYSCHAR, 194, 344 
WM_SYSCOLORCHANGE, 345 


WM_SYSCOMMAND, 345 
message wParam value 132 
values, 345 - 


_ WM_SYSDEADCHAR, 346 


WM_SYSKEYDOWN, 194, 346 
WM_SYSKEYUP, 194, 346 


_ WM_SYSMSGFILTER, 251, 


nCode values, 252 
WM_TIMECHANGE, 346 


_ WM_TIMER, 347, 805, 847-50 


WM_UNDO, 347 

WM_USER, 347 
WM_VKEYTOITEM, 347-48 
WM_VSCROLL, 148, 348 
WM_VSCROLLCLIPBOARD, 348 
WM_WININICHANGE, 349 
WNDCLASS, 


definition in WINDOWS. H, 29 


. structure, 3 
WndProc, 2, 122, 128 
WndProc() function, 

creating owner-drawn menu 

items, 113-14 

outline of, 307 
WORD, 612, 918 
WParam, 11 
WriteComm, 825 
WritePrivateProfileString, 801- 2 
WriteProfileString, 802-3 
WS_BORDER, 23 
WS_CAPTION, 23 
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WS_CHILD, 13 
WS_CHILDWINDOW, 23 
WS_CLIPCHILDREN, 23° 
WS_CLIPSIBLINGS, 23 
WS_DISABLED, 23 


WS_DLGFRAME, 23 - 


WS_GROUP, 23 
WS_HSCROLL, 24 
WS_ICONIC, 24 
WS_MAXIMIZE, 24 
WS_MAXIMIZEBOX, 24 
WS_MINIMIZE, 24 
WS_MINIMIZEBOX, 24 


~ WS_OVERLAPPED, 24 
- WS_OVERLAPPEDWINDOW, 24 


WS_POPUP, 24 
WS_POPUPWINDOW, 24 


_ WS_SYSMENU, 24 


WS_SYSMODAL, 555 
WS_TABSTOP, 24, 558 
WS_THICKFRAME, 24 
WS_VSCROLL, 24 
Wsprintf, 480-32 
Wsprintf(Q), 
extra formatting codes, 431 
format codes, 481 
WuUsage, 672 
Wvsprintf, 482-33 
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XOR mask, 711 


Jim Conger began programming in 1972 while studying Engineering at the 
University of Southern California. He has been writing programs ever since for 
a variety of computers. Most of his early work was done on mainframe com- 
puter systems using FORTRAN and BASIC for process simulation work. Jim 
started programming microcomputers in the early 1980s while living in Lon- 
don. These projects were primarily financial models, using BASIC, Pascal and 
assembly language. His first C programs were written in 1983 while under the 
CP/M operating system, and has continued using C and C++ under MS-DOS 
and Windows. a 
Jim’s hobby of playing woodwind instruments lead to his interest in com- . 

puter music. He is the author of two books on the subject, C Programming for MIDI (M&T Books, 1989), and MIDI 
Sequencins i C (M&T Books, 1989). Jim lives in California with his wife and two children. . 


Geisthon 


Production for this book used desktop publishing techniques—every phase of the book involved the use of Sstaputer 
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